docs(fix): 修正审计抓出的文档/UX 失实（成员制/hooks/跨机auth警告/printHelp）#205
Open
raysonmeng wants to merge 1 commit into
Open
Conversation
修复审计发现的 4 处文档与实际实现不符的问题：
1. docs/10 §2：删除「broker subscribe 不做成员校验」的过时声明（实际
broker.ts 在 subscribe 和 publish 路径均有 isMember 门控，closed-by-default，
fail-closed）；改为如实描述三层鉴权（Tailscale ACL + PSK + 成员制授权）。
2. docs/09 附录C：修正 hooks.json 示例 —— 钩子类型从 TaskCompleted（Claude Code
不存在此类型）改为 Stop；命令从 abg publish --from-hook 改为
bash "${CLAUDE_PLUGIN_ROOT}/scripts/publish-completion.sh"；
删除不存在的 async/timeout 字段。与 plugins/agentbridge/hooks/hooks.json 对齐。
3. docs/manual/使用手册.md + manual-en.md：
a) 将 abg install:global（不存在的 abg 子命令）改为 bun run install:global。
b) §3.3(b) 跨机 auth 流程标注 ⚠️ 当前不通：abg auth login 在本机自签新 token，
但 broker 只认 broker 机 collab.db 里的 token（本机自签 → 4401）；
标注手动 workaround + 正式 CLI 在 feat/v3-xnet-onboarding 中。
4. src/cli.ts printHelp：补全已实现但遗漏的 room add <roomId> <identityId>
和 room remove <roomId> <identityId> 子命令描述。
---
fix(docs): correct stale doc/UX bugs — membership auth, hooks, manual, printHelp
1. docs/10 §2: remove false claim "broker subscribe skips room membership check"
(broker.ts gates both subscribe and publish on isMember, closed-by-default,
fail-closed); restate accurate three-layer auth model.
2. docs/09 Appendix C: fix hooks.json example — hook type TaskCompleted (which
does not exist in Claude Code) → Stop; command → actual script path;
drop non-existent async/timeout fields. Aligned with real hooks.json.
3. manual (ZH + EN): fix abg install:global (invalid subcommand) → bun run
install:global; mark §3.3(b) cross-machine auth as ⚠️ currently broken
(self-signed local token unknown to broker → 4401); add workaround note.
4. src/cli.ts printHelp: add missing room add/remove subcommand descriptions.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012rhWKm1VUSnEVxmjpYwNfc
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
修 6 维度审计实证出的文档/UX 失实 bug——照着做会失败的命令 + 与代码相反的论断。
变更 / Changes（commit
1e1e1df）abg auth issue/login --token/room invite正在 P1 实现）TaskCompletedhook 类型 →Stop；hooks.json 示例改对（bash publish-completion.sh，无 async/timeout）；「Stop 会话结束触发」→「每轮触发」install:global→bun run install:global（前者非 abg 子命令、照敲报错）room add/remove测试 / Test plan
bun run typecheck0 错，bun run build:pluginOK注：跨机文档段落待 P1 跨机 onboarding（abg auth issue/login --token/room invite）实现后重写为真实可跑流程。
🤖 Generated with Claude Code