Superself 插件实战用selfCLI 为 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 superself0.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.mdgh 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中包含!-- superself:begin与!-- superself:end --之间的托管块managed block运行self setup时该目录能解析到一个已注册的项目会打印 workspace、project 与 store 路径。反之若self --version失败则跳过该技能。此外 Skill 注明它是针对superself0.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 idself 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会话如何从头到尾驱动该 CLIself help contextself context渲染什么、为什么某些内容会缺失self help records每种记录背后的实体、记录如何被更正self help placementscope、priority、exposure——记录如何获得它在上下文中的位置self help work工作图outcomes、evidence、criteria、proposalsself help goals长期目标、objective、milestone 以及达成它们需要什么self help workspacestore、其中的项目、以及如何在机器间迁移这些指南与 Skill 文档互补Skill 给出 Agent 的行为流程主题指南给出每类记录的底层模型。安全与披露边界plugins/superself/README.md 中有两段明确披露值得引用维护方声明本插件由 Superself 作者fxylabs维护包装的是其自家的开源 CLI插件不含 hooks、不含 MCP serverSkill 只会在 shell 中发出self命令。托管层说明钉住的superself0.6.1不含任何网络代码、不连接任何服务0.7.0 及以后的版本才加入可选托管服务self login、self app但本 Skill 记录的核心动词始终本地且免费。结合本仓库的插件目录设计docs/plugins.md 中每个插件可含 agents/、commands/、skills/ 三部分superself是“单技能插件”的典型样本单点职责、最小 token 占用、天然可组合——这正是本仓库所倡导的插件设计原则在“外部 CLI 适配”场景下的体现。【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考