Conversation
…st standards From real-world experience building slock.ai CLI adapters: - oneshot: add network-empty diagnosis, SPA baseURL bundle search, Tier 2.5 localStorage Bearer template (with multi-tenant X-Server-Id pattern), updated auth quick-reference, file path note, opencli browser verify test flow - explorer: add Tier 2.5 to decision tree and strategy table, update test section with opencli browser verify + Done standard, fix Step 5 path to ~/.opencli/clis/, add 4 new pitfall rows (SPA HTML, 400 context header, empty network, wrong dir)
…adapters Fix reviewer blocking issue: - Remove the contradictory "~/.opencli/clis/" note that mixed user-local and repo-contributor workflows; replace with explicit two-scenario callout in Step 4, Step 5, pitfall table, and oneshot test section - Template comments in oneshot restored to clis/<site>/<name>.ts (repo path) Add "抗变更模式" section to explorer, based on opencli's own production code: - Pattern 1: dynamic queryId discovery (twitter/shared.ts resolveTwitterQueryId) — scan loaded JS bundle by operationName (stable) to find queryId (unstable) - Pattern 2: semantic DOM priority fallback (web/read.ts) — article > [role=main] > main > class-hint > body, pick largest text block - Pattern 3: ordered selector array + timestamp comments (xiaohongshu/publish.ts) — first-match wins, comment records UI version and observed attribute values - Pattern 4: nullish-coalescing field multi-path (xiaohongshu/user-helpers.ts) — covers camelCase/snake_case variants without assuming fixed key name
- Shrink main SKILL.md from 994 to 270 lines — core workflow only
- Extract all TS templates (Tier 1~4, pagination) to references/adapter-templates.md
- Add error handling standard: { error, remedy } pattern (remedy > hint)
- Add Tier 2.5 localStorage Bearer template with multi-tenant X-Server-Id example
- Extract cascading requests, tap debug, verbose mode, anti-change patterns to references/advanced-patterns.md
- Extract record workflow to references/record-workflow.md
browser verify only reads ~/.opencli/clis/, not repo's clis/. Split all verify instructions: - Repo 贡献: npm run build + opencli <site> <cmd> - 私人 adapter: opencli browser verify <site>/<name> Fixes blocker in explorer:L209, L224 and oneshot:L286, L298
explorer: add path decision matrix before core workflow oneshot: add explicit stop/switch conditions (when to escalate to explorer) both: add keep-in-sync comment on the two-scenario verify block
…remedy→help
slock/utils.ts: new — getSlockContext(), resolveChannelId()
- Shared token + workspace resolution, no more 4-line duplication
- UUID regex (/^[0-9a-f]{8}-...$/) replaces fragile !includes('-')
- Returns { error, help } instead of throwing
tasks.ts / members.ts / send.ts:
- Import from utils.ts, remove all duplicated auth boilerplate
- All errors return [{ error, help }], no more throw
- members.ts: add limit arg (was unbounded before)
docs: rename remedy → help across all skill references
… help } pattern
- slock: agents, channels, messages, servers now use getSlockContext/resolveChannelId
from utils.ts; error handling uses { error, help } return instead of bare throws
- linux-do: export fetchLinuxDoJson from feed.ts; migrate search, topic, categories,
tags, user-posts, user-topics from pipeline+throw to func() using fetchLinuxDoJson
- xueqiu: add utils.ts with fetchXueqiuJson helper; migrate hot, feed, search, stock,
watchlist, hot-stock, groups, kline, earnings-date from pipeline+throw to func()
When a command declares columns (e.g. ['rank', 'title', 'value']) but
returns an error row ({ error, help }), the declared columns would
render empty cells. Now resolveColumns detects the error key and falls
back to the row's actual keys, making diagnostics visible in all output
formats.
jackwener
force-pushed
the
docs/skill-improvements-deep
branch
from
1b04d84 to
3a4eb58
Compare
Slock adapters should be in a separate PR, not bundled with the adapter refactor and skill docs improvements.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
opencli-explorerandopencli-oneshotSKILL.md: add router decision matrix, stop/escalation conditions, Tier 2.5 localStorage Bearer template, anti-change patterns, and fixbrowser verifyscenario (repo contributors must usenpm run build + opencli ..., notbrowser verifywhich only reads~/.opencli/clis/)references/adapter-templates.md(Tier 1–4 templates, utils.ts extraction pattern,{ error, help }error standard) andreferences/advanced-patterns.md(cascading requests, tap debug, verbose validation)utils.ts(getSlockContext,resolveChannelIdwith proper UUID regex); apply{ error, help }return pattern to all 7 adapters (agents, channels, members, messages, send, servers, tasks)fetchLinuxDoJsonfromfeed.ts; migratesearch,topic,categories,tags,user-posts,user-topicsfrompipeline+ rawthrowtofunc()usingfetchLinuxDoJson— error handling now usesAuthRequiredErrorutils.tswithfetchXueqiuJsonhelper (returns{ error, help }on 401/403/parse failure); migratehot,feed,search,stock,watchlist,hot-stock,groups,kline,earnings-datefrompipeline+ rawthrowtofunc()Test plan
npm run buildpasses (255 entries)opencli slock channels— returns channels or{ error: 'Not logged in', help: ... }opencli slock messages general— uses UUID regex for channel ID detectionopencli linux-do search typescript— returns results viafetchLinuxDoJson(no pipeline)opencli linux-do categories --subcategories— subcategory cascade worksopencli xueqiu hot— returns viafetchXueqiuJson(no pipeline)opencli xueqiu stock SH600519—{ error, help }on not-logged-in