symbion Skill 技能

技能简介

symbion 是一个"按项目"的笔记本与工单登记册，专为小项目里的人类开发者与编码 Agent 协作而设计，通过一个 CLI 统一驱动。CLI 可独立使用；Agent 侧则以共享 Skill 与 SessionStart 钩子的形式支持 Claude Code 与 Codex。每条笔记都有日期、作者、可撤回，并锚定在一个稳定对象上——一次 commit、一个文件、一个自定义条目，或整个项目。默认提供七种类型：check（带日期的验证）、decision（架构决策记录 ADR）、bug、task、question（待负责人回答）、idea（搁置）与 note。存储是项目旁边一个独立的 git 仓库（JSONL 格式），切换旧分支永远不会"时间旅行"你的工单。

核心能力

1. 七种记录类型 + 自定义类型：类型只是打在 status/parked/verdict 三个位上的标签，可在 symbion.toml 的 [kinds] 中自行声明，symbion schema 打印类型表。
2. Arc（史诗）视图：命名工作线以清单形式跨对象展示待办，arc create / arc seed / arc todo / arc reconcile 管理，任务随代码树变化自动识别存活、改名或过期。
3. Agent 集成：symbion init 一键把 Skill 链接到 ~/.claude/skills/symbion 或 ~/.agents/skills/symbion，并注册 SessionStart 钩子；每次会话开始自动汇总未关闭条目、他人新增/修改的条目与逾期项。
4. 目录（Catalogs）与解析器：目录是一条打印名称列表的 shell 命令（如 git ls-files '*.py'），可对整目录批量生成任务；对测量值等易混淆名称可配自定义解析器，绝不用子串匹配兜底。
5. 本地 Web 界面：symbion serve 起一个本地页面，含看板、标签/类型/作者过滤、全文搜索、快捷键速记、版本历史与提交/推送按钮。
6. 终端友好与 git 安全：表格输出带状态标记与年龄，管道输出纯文本供脚本与 Agent 消费；写入永不自动提交，symbion commit 由你控制，可挂 gitleaks 预提交钩子防泄密。

安装配置

1. 环境要求：Python 3.11+ 与 git（钩子需要 bash，Windows 用 WSL）。
2. 安装：pipx install 'symbion[gui]' 或 uv tool install 'symbion[gui]'；[gui] 附带 Web 界面，不需要可去掉。
3. 启用 Agent 集成：在项目根执行 symbion init --yes（默认 Claude Code），--agent codex 或 --agent both 切换；Codex 需 codex --add-dir ../-notes 授予存储写权限。
4. TAB 补全：把 eval "$(symbion completion zsh)" 等对应行写入 shell rc 文件，可补全动词、标志与存储内的类型、目标、行 ID、Arc ID。
5. 告知 Agent：在 CLAUDE.md 或 AGENTS.md 加一行——"我们用 symbion 记录持久笔记与工单，遇到摩擦要主动反馈"。

使用步骤

1. 初始化存储：symbion init --yes，在项目旁创建 ../-notes git 仓库并链接 Skill 与钩子。
2. 写第一条验证：symbion add check --target commit:HEAD --checked "pytest -q" --result "147 passed"，记录当时仓库状态，之后可随时复验是否过期。
3. 建立清单：symbion arc create 建弧，symbion add task --target ... --arc-id ... 逐条挂任务，arc todo 看未完成项，resolve 勾销。
4. 会话中协作：Agent 启动时钩子自动汇总上下文；人可随时 ! symbion add ... 补记录，作者自动记为当前 Agent 或 git 用户名。
5. 会话结束：symbion commit -m "..." 提交存储，symbion push（有远端时）同步；symbion summary 查看未提交数量。

适用场景

1. 长期项目的知识沉淀：把散落在 commit message、TODO 注释和聊天记录里的决策与验证集中登记。
2. 人机结对开发：Agent 每次会话启动即可恢复全部未决问题、待办与历史决策，不再重复解释背景。
3. Bug 与工单跟踪（轻量）：不想上 Jira 的小项目，用 bug/task/question 类型做本地化工单。
4. 验收与回归验证：check 类型绑定 commit 与检查命令，HEAD 移动后自动显示过期，防止"过期的绿灯"。
5. 多分支/多工作树并行：存储独立于项目 git 历史，链接 worktree 共享同一存储。

适用人群

独立开发者、小型开源项目维护者、使用 Claude Code / Codex 等编码 Agent 的团队，以及希望给 AI 协作者一个"可持久读写项目记忆"的工程负责人。

工作原理

symbion 把记录存在项目旁边的独立 git 仓库中：notes.jsonl（提交后只追加，更正即新增一行并 supersede 旧行）、arcs.jsonl（工作弧）与 symbion.toml（类型、目录、解析器配置）。写操作从不自动 commit，保证 git 失败也不会阻塞记录。SessionStart 钩子在每次 Agent 会话开始时运行 symbion summary，把未关闭条目、他人新增内容与逾期项注入上下文；Agent 通过 Skill 文档学会用同一 CLI 读写。因为存储与项目代码分离，切换分支不会带走或覆盖工单，而独立的 git 历史又天然提供了版本追踪与协作能力。

官方链接

• PyPI：https://pypi.org/project/symbion/
• GitHub：https://github.com/phreakocious/symbion
• 设计文档：https://github.com/phreakocious/symbion/blob/main/docs/superpowers/specs/2026-09-04-symbion-design.md
• Agent Skill 手册：https://github.com/phreakocious/symbion/blob/main/src/symbion/data/skill/SKILL.md