用途:Superself 以独立于代码的 git 仓库、只追加事件日志来管理项目状态,包括目标、决策、工作单元和报告;状态按需派生,不需要手工维护。本技能用于指导智能体通过 self CLI 读写这些状态。
适用条件:项目 AGENTS.md 或 CLAUDE.md 中存在 <!-- superself:begin 与 <!-- superself:end --> 区块,或 self setup 能打印出当前目录解析到的 workspace、project 和 store。若 self --version 失败,说明项目未使用 Superself,应跳过本技能,不得自行编造。
安装与版本:npm install -g superself@0.6.1,需要 Node 22.12 及以上。本技能针对 superself@0.6.1;其他主次版本可能改动命令或参数,使用前可用 self <command> --help 确认。
会话开始:运行 self context,其输出应视为当前事实,包含目标、生效的决策与约定、未完成工作和近期报告。缺失内容通常是被人为排除在渲染集之外;用 self search <query> 查找未被 context 包含的有效记录,用 self work show <id> 查看某个单元的完整简报与报告历史。
工作中:实质性工作要挂到工作单元上。用 self work add "<required outcome>" 创建单元(outcome 是必须成真的结果,不是任务),再用 self work start <id> 开始;start 会读取简报并记录本次会话接手该单元。若其他会话已持有,CLI 会提示是谁、从何时起,但不会拒绝,需自行判断后继续。提交后报告进展:self report <id> "<what happened>",当前 HEAD 提交会自动作为证据;可用 --evidence <commit|note> 附加其他证据,或用 --file <path> 附加更长的简报。记录用户确认的决策:self decide "<text>" --why "<reason>";用户未确认时用 --proposed。每个事件只记一个决策。受阻时用 self work block <id> --on decision|dependency|external --why "..."。被取代或转移时用 self work retire <id> --why "..." [--successor <id>],不要将这类单元标为完成,也不要虚假地保持阻塞。发现目标与当前状态有差距时,用 self work propose 及其简报提议工作,由用户接受或拒绝。用户批准下一步或续做时,立即用 self work add 登记及背景;只存在于对话中的计划会随对话结束而丢失。
收尾:self work done <id> 仅在报告带有提交或产物,或 done 自身说明可验证发生了什么时才能关闭单元,例如 self work done <id> --report "<what verifiably happened>";仅有声称会被拒绝,且声明的条件未全部满足前会一直受到门控。记录文本一经确认不可变,需通过重述修正:任意 add 类命令加 --supersedes <id> 记录新措辞并保留脉络;retract 可在无替代内容时撤回记录。
可信规则:记录(事件、决策、报告、约定)用英语书写,以便下一位打开者阅读;回复用户时使用其自己的语言。分支通过拉取请求进入 main,合并控制权归 PR 审查与 CI;Superself 负责上下文与工作图,不负责合并门禁。不要手工编辑生成的状态文件或 .superself/ 下任何内容。在没有 superself 区块的项目中,先运行 self setup;若解析到已注册项目,询问用户一次是否运行 self connect(会把受管区块写入 AGENTS.md 或 CLAUDE.md);若未解析到项目,询问用户一次是否用 self project init 注册。切勿自行注册或连接项目。
限制:项目须已使用 Superself;CLI 版本可能改变命令与参数;合并门禁不由本工具控制;记录不可变,只能通过重述或撤回修正。深入了解可运行 self --help、self <command> --help,以及随 CLI 提供的主题指南:self help agents、self help context、self help records、self help placement、self help work、self help goals、self help workspace。