Superself 插件实战：用 `self` CLI 为 Agent 会话管理可审计的项目状态-编程实验室

Superself 插件实战：用`self`CLI 为 Agent 会话管理可审计的项目状态

【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents

导读

Superself 是 agents24 插件市场（本仓库）中一个特殊的插件：它不提供新的 Agent、命令或钩子，而是交付一个名为superself的 Skill，指导 Agent 驱动 Apache-2.0 的selfCLI，把项目的目标（goals）、决策（decisions）、工作单元（work units）、报告（reports）以追加式事件日志形式版本化保存在一个独立于代码的 git 仓库中。本文基于 plugins/superself/README.md 与 plugins/superself/skills/superself/SKILL.md 展开，讲清它的设计动机、安装要求、完整命令流（会话开始 / 工作中 / 收尾 / 可信规则），并结合仓库中的插件清单与多 harness 生成机制说明它如何被安装到不同 Agent 环境中。

为什么需要“状态版本控制”

普通代码仓库管理的是代码的演进，而会话状态——本次会话的目标、已确认的决策、正在进行的工作单元、进展报告——通常散落在对话历史里。对话一结束，这些信息就丢失；下一个会话不得不重新推断。Superself 的思路是把这类状态当作一等公民：

状态以追加式事件日志（append-only event log）记录，任何记录一旦确认就不可篡改；
日志存放在一个与代码分离的 git 仓库中，既不污染代码提交历史，也不依赖任何外部服务；
会话所需的“当前状态”是**按需从日志折叠（derive）**出来的，没有任何手工维护的中间文件。

本仓库对它的定位与上述思路一致：docs/plugins.md 的工作流分类中这样描述它——“Drive the SuperselfselfCLI: project state (goals, decisions, work units, reports) outside the code repo, context at session start, done gated by evidence”。也就是说，它解决的是“下一个会话如何无缝接续上一个会话”这一核心问题。

安装与前置要求

CLI 环境要求

需要selfCLI 位于 PATH 中，安装命令为npm install -g superself@0.6.1；
要求Node 22.12+；
无需注册账号、无需任何远程服务——0.6.1 是本地优先（local-first）实现。

一个关键约束是版本被钉死（pinned）在 0.6.1。plugins/superself/README.md 明确说明：版本升级必须通过本仓库的 PR 流程进行。原因是 0.7.0 及以后引入了可选的托管服务（self login、self app），而当前这个 Skill 所记录的核心动词保持本地、免费，钉住版本可以保证这份清单停留在“经过审查的版本”上。

Skill 对版本不匹配还有一条降级策略：如果self --version失败，说明项目并未使用 Superself，此时 Skill 应跳过自身，绝不应凭空手工编造任何状态记录。

插件在仓库中的形态

本插件结构非常精简，只含两部分：

plugins/superself/ ├── .claude-plugin/plugin.json # Claude Code 插件清单 ├── .codex-plugin/plugin.json # Codex 插件清单 └── skills/superself/SKILL.md # 唯一交付物：superself 技能

plugins/superself/.claude-plugin/plugin.json 声明插件名superself、版本1.0.0、作者 fxylabs、许可证 Apache-2.0，并将唯一交付物指向skills/；
plugins/superself/.codex-plugin/plugin.json 额外声明"skills": "./skills/"，供 Codex CLI 直接读取 SKILL.md。

这与仓库整体的“多 harness 单一来源”设计一致：docs/harnesses.md 说明所有插件以plugins/下的 Markdown 为唯一事实来源，由tools/adapters/生成各 harness 的原生产物。对本插件而言，交付物只有 Skill，因此它天然可移植。

安装到各 harness

在 Claude Code 中按 docs/plugins.md 的流程安装：

/plugin marketplace add wshobson/agents /plugin install superself

/plugin marketplace add只会让全部 94 个插件可供安装，不会把任何 Agent 或工具加载进上下文；/plugin install superself才把该插件的唯一 Skill 载入。

如果只想取这一个 Skill（不装插件、不克隆仓库、不生成任何产物），可以使用两种“纯 Skill”安装器（见 docs/harnesses.md）：

gh skill install wshobson/agents superself --agent claude-code # GitHub CLI 2.90+ npx skills add wshobson/agents --skill superself -a claude-code # vercel-labs/skills

注意一个坑：两个安装器都按裸技能名（bare skill name）安装到<agent>/skills/<skill>/目录，superself是有效选择器，而plugins/superself/superself这类带插件前缀的写法无效。

Skill 的触发条件

superself技能由 plugins/superself/skills/superself/SKILL.md 的 frontmatter 描述定义：

Use when a project keeps its state in Superself (a<!-- superself:beginblock in AGENTS.md or CLAUDE.md, orself setupresolves the directory to a registered project)…

即出现以下任一情况时，Agent 应当启用该技能：

项目的AGENTS.md或CLAUDE.md中包含之间的托管块（managed block）；
运行self setup时，该目录能解析到一个已注册的项目（会打印 workspace、project 与 store 路径）。

反之，若self --version失败，则跳过该技能。此外 Skill 注明它是针对superself@0.6.1编写的，其他主版本或次版本可能移动过动词或标志位，因此依赖某个动词前应先用self <command> --help确认。

会话开始：读取派生的上下文

会话开始时，Agent 的首要动作是运行：

self context

这条命令输出的内容——目标、生效中的决策与约定、未完成的工作、最近的报告——是从日志折叠出来的当前真值（current truth），不是手工编写的。self context的渲染逻辑与“某条记录为什么不在上下文里”的解释，可通过 CLI 自带的主题指南查看：self help context。

如果上下文缺少某项内容，那是有意将其移出了渲染集合，而不是丢了。此时：

self search <query>：检索日志中未被上下文渲染的活动记录；
self work show <id>：打印某个工作单元完整的任务简报（brief）与报告历史。

self context的完整动词清单可用self --help查看，单个命令的 flags 用self <command> --help查看（不会触碰任何状态）。

工作中：把实质性工作挂到工作单元

创建并认领工作单元

实质性工作必须挂靠到一个工作单元（work unit）上。创建时，产出物（outcome）必须是“什么必须变为真”，而不是“要做什么任务”：

self work add "<required outcome>" self work start <id>

self work start <id>会读取该单元的任务简报，并记录“本会话认领了这个单元”。如果另一个会话正持有该单元，CLI 会告知持有者是谁、从何时开始持有，但不会拒绝——由当前 Agent 自行判断并继续。这保证了并行会话之间不会互相死锁。

提交带证据的进展报告

提交代码后报告进展：

self report <id> "<what happened>"

报告会自动把当前 HEAD commit 作为证据附加。其余参数：

参数	作用
`--evidence <commit\\|note>`	附加其他证据（某个 commit 或一段说明）
`--file <path>`	附加更长的简报文件

记录决策

用户已确认的决策，用：

self decide "<text>" --why "<reason>"

用户尚未确认的，则加--proposed标记。规则是每条事件只记录一个决策（One decision per event）。

阻塞、废弃与提议

受阻时：self work block <id> --on decision|dependency|external --why "..."（阻塞原因限定为决策、依赖、外部三类）；
被取代或迁移时：self work retire <id> --why "..." [--successor <id>]；
绝不把上述单元标记为 done，也绝不留下虚假的阻塞标记；
发现目标与当前状态之间存在差距时，用self work propose连同任务简报一起提议，由用户接受或拒绝；
用户批准了下一步或延续事项时，立即用self work add连同上下文背景登记下来——只存在于对话中的计划，会随对话结束而消失。

收尾：没有证据就不能宣告完成

self work done <id>

关闭工作单元的前提是报告携带了 commit 或 artifact，或者done 本身陈述了可验证发生了什么：

self work done <id> --report "<what verifiably happened>"

规则很硬：空口声明（bare claim）会被拒绝，并且已声明的标准（criteria）会作为门槛，直到每一条都被覆盖才会放行。这正是 docs/plugins.md 中 “done gated by evidence” 的含义——完成必须由证据门控。

记录的更正方式：不可变 + 溯源

记录一旦确认就不可变。需要更正时，不要改写原记录，而是重新陈述并保留血缘：

在任何 add 动词上加--supersedes <id>：写入新的措辞并保持谱系（lineage）连续；
retract：撤回一条记录，且没有替代物。

这条“restate 而非 edit”的机制也体现在self help records主题指南中（一条记录背后的实体，以及记录如何被更正）。

保持状态可信的规则

Skill 明确了四条底线规则：

语言：记录（事件、决策、报告、约定）一律用英语书写，以便任何打开它们的人都能读懂；但回复用户本人时用对方的语言。
合并控制归 PR：分支合并到 main 必须通过 Pull Request——PR review 与 CI 拥有合并控制权；Superself 只负责上下文与工作图，不是合并门禁。
禁止手改生成文件：绝不手工编辑生成的状态文件，也不得触碰.superself/下的任何内容。
注册 / 连接需征求用户：在没有 superself 托管块的项目中，先运行self setup。若它能把目录解析到已注册项目，则问一次用户是否运行self connect（该命令把托管块写入AGENTS.md或CLAUDE.md）；若解析不到任何项目，则问一次是否用self project init注册。绝不能擅自注册或连接项目。

这条“托管块写入哪个文件”的行为与 harness 的上下文文件约定相呼应：本仓库在 docs/harnesses.md 中记录了 Claude Code 读CLAUDE.md、Codex/Cursor/OpenCode/Antigravity 读AGENTS.md，所以self connect恰好覆盖这两种入口。

深入资料：随 CLI 分发的主题指南

self --help列出全部动词；self <command> --help打印单个命令的 flags 且不触碰状态。更系统的学习资料随 CLI 一起分发，Skill 中列出的主题指南如下：

命令	主题
`self help agents`	会话如何从头到尾驱动该 CLI
`self help context`	`self context`渲染什么、为什么某些内容会缺失
`self help records`	每种记录背后的实体、记录如何被更正
`self help placement`	scope、priority、exposure——记录如何获得它在上下文中的位置
`self help work`	工作图：outcomes、evidence、criteria、proposals
`self help goals`	长期目标、objective、milestone 以及达成它们需要什么
`self help workspace`	store、其中的项目、以及如何在机器间迁移

这些指南与 Skill 文档互补：Skill 给出 Agent 的行为流程，主题指南给出每类记录的底层模型。

安全与披露边界

plugins/superself/README.md 中有两段明确披露，值得引用：

维护方声明：本插件由 Superself 作者（fxylabs）维护，包装的是其自家的开源 CLI；插件不含 hooks、不含 MCP server，Skill 只会在 shell 中发出self命令。
托管层说明：钉住的superself@0.6.1不含任何网络代码、不连接任何服务；0.7.0 及以后的版本才加入可选托管服务（self login、self app），但本 Skill 记录的核心动词始终本地且免费。

结合本仓库的插件目录设计（docs/plugins.md 中每个插件可含 agents/、commands/、skills/ 三部分），superself是“单技能插件”的典型样本：单点职责、最小 token 占用、天然可组合——这正是本仓库所倡导的插件设计原则在“外部 CLI 适配”场景下的体现。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Superself 插件实战：用 `self` CLI 为 Agent 会话管理可审计的项目状态