fxylabs/superself

Superself

开放的公司状态运行时。

模型有上下文。智能体有运行时。公司需要状态。

公司状态是一个组织意图、已做出的决定、正在做的事、可能授权的事以及能够证明的事的持久、带版本的真相。公司状态运行时将该状态转化为上下文、就绪的工作、证据门控的完成以及下一个公司状态。目前引擎强制执行的策略覆盖原始状态动词和完成门；通过 WorkSpec 契约进行的受监督执行以及受能力门控的预设动词是既定目标——
docs/roadmap.md 划定了这一边界。

[!IMPORTANT]
Superself 处于早期 alpha 阶段。本地 self CLI 以及
今天哪些功能可用？ 中描述的基础功能
现在即可使用。完整的公司状态运行时循环是项目的方向，而非
本版本声称已完成的能力。在事件模式和动词稳定之前，
预计会有破坏性变更。

什么是 Superself？

Superself 正在构建开源的公司状态运行时：如今是超越任何单一上下文窗口的持久状态，目标是超越任何单个人注意力跨度的受治理执行。人设定方向、做出重大决策，并保持问责。智能体承担大部分规划、日常执行、恢复、验证和报告。

它的存在是为了在人类和智能体之间保持一种上下文的同步，从单个项目到整个公司：每个决策为何做出以及是否仍然成立，每项工作为何存在、它贡献于什么、进展到何种程度，以及什么在阻碍它。它刻意保持模型中立和会话中立——任何智能体、任何工具、任何会话都读写同一状态——因为智能体原生公司不会建立在某个供应商的记忆之上。

今天交付的是 self CLI：一个本地优先的垂直切片，不需要 Superself 账户，并将主工作区保留在你的机器上。Git 为你的代码做版本管理；Superself 为项目本身做版本管理——目标、决策、工作单元、报告和证据——作为仅追加日志中的类型化事件，智能体所需的上下文按需从该日志派生。

为什么我的智能体每次会话都从零开始？

长期运行的项目比每一次聊天、上下文窗口、模型和人类记忆都更长寿。目标、决策、被否决的方向、进展和证据散落在各个会话和工具中。每个新智能体都要花时间重建项目，遗漏约束，或者重复一个已经做出的决定。

手工维护的指令文件和交接笔记能短暂起作用，随后就会过时或变得太大而无法使用。项目需要一种能在其会话之后存续的规范状态，以及一种只为下一个动作编译该状态中相关部分的方法。这就是连续性天花板，也是 Superself 瞄准的第一个天花板。

为什么增加更多智能体不能扩展工作？

当一个人必须分解每一个请求时，智能体执行就无法扩展，
选择每一个后续任务，观察每一个过程，批准每一个步骤，恢复每一次失败，并验证每一次完成。人类变成了系统的调度器、消息总线和重试循环。这就是监督上限。

目标不是移除人类控制。而是将人类注意力花在判断力和问责制重要的地方，同时系统在明确的边界内处理常规规划、执行、协调、恢复、验证和报告。

这两个上限相互强化：没有持久上下文，执行就无法安全地委托；而如果一个人仍然必须驱动每一个动作，持久上下文的价值就有限。

我需要 Superself，还是 CLAUDE.md 就够了？

像 CLAUDE.md 和 AGENTS.md 这样的指令文件是放置稳定操作规则的正确位置，而 Superself 会写入它们而不是替换它们：self connect 渲染一个受管理的块，教会任何终端代理该协议，以及用 --public 记录的约定。项目记录的其他所有内容都留在存储中，不在被跟踪的文件里。

指令文件无法保存的是随每个会话而变化的状态：哪些决策是当前的以及为什么，哪些工作是开放的以及谁持有它，什么证据关闭了一个单元，什么被尝试过并被拒绝。手动编辑保存这些内容的文件在写下的第二天就会过时，而且它没有历史、没有证据，也没有办法限制下一个会话读取的内容。Superself 将这些变化的状态保存在仅追加的事件日志中，按需从中派生 self context，并让指令文件做它擅长的事。

这与 Linear 或 Jira 这样的问题跟踪器有何不同？

问题跟踪器协调人：工单、状态和评论，在 Web 应用中读取和更新。Superself 记录代理行动所需的状态：带有理由和谱系的决策、管理工作如何完成的约定、目标和目的、带退出标准的里程碑，以及工作单元——其“完成”会被拒绝，直到声明携带证据——一次提交、一个工件，或一份关于可验证发生了什么的报告。

它的定位也不同：本地优先、由 git 支持、以 CLI 为形态，因此代理已经运行的同一个工具就是读写界面，上下文是为下一个动作编译的，而不是浏览的。Superself 不替代代码审查或 CI——分支通过拉取请求到达 main，合并控制有意留给 PR 审查和 CI。

我需要向量数据库或记忆服务吗？

不需要。保存公司的工作上下文已经用 wiki、Notion、Obsidian 和一波代理记忆产品尝试过，反复出现的失败不是检索能力——而是意图的记录会衰减，且没有任何东西强制其真实性。这不需要复杂的技术来修复。它需要持久的、被断言的记录，并在写入路径上有规则。

Superself 的状态是纯文本：仅追加的 JSONL 日志中的类型化事件
在一个由你的机器拥有的 git 仓库中，折叠成任何工具都能读取的 markdown。它可以被 grep、被 diff、被 blame，并且可移植；self search 直接从实时记录中作答，无需索引服务器，而且它的一切都不锁定于某个模型、某个供应商或这个十年。

我该如何开始？

需要 Node.js 22.12 或更新版本。

npm install -g superself

初始化应存放机器工作区状态的目录，然后注册一个现有项目：

mkdir -p ~/self-workspace
cd ~/self-workspace
self init --git

cd ~/path/to/my-project
self project init
self goal add "Ship the first trustworthy release"
self decide "Keep customer data local" --why "This project handles private data"
self work add "The payment flow passes its end-to-end proof"
self context

按照入门指南走完完整的设置路径，包括独立的状态仓库、受管理的 agent 块、私有 Git 同步，以及在另一台机器上的恢复。按照长期项目指南，通过里程碑、报告和有证据支撑的完成，把一个真实的成果跨会话、跨 agent 地延续下去。

运行 self --help 查看完整的命令面。主要的命令族有：

- 项目状态：goal、decide、convention、objective、milestone；
- 它们底层的实体语法：state、alias；
- 工作与证据：work、report、artifact；
- 过程账本：work started、work exited；
- 上下文与检查：context、status、search、view；
- 工作区归属：project、workspace、remote、sync、clone。

agent 在会话开始时能得到什么？

self context 打印出 agent 所需的派生上下文：目标、生效中的决策与约定、未完成的工作，以及最近的报告——由状态生成，从不手工维护。self work show  恢复某个单元的完整状态，--history 则翻页查看它自身的事件；self search  拉取上下文遗漏的实时记录，横跨每一个已注册的项目。AGENTS.md 和 CLAUDE.md 中的受管理块教会终端 agent 加载并维护该状态，而且该块会在每次折叠时刷新。

阅读公司状态与上下文，了解仅追加的事件历史、折叠后的当前状态、生成的视图、agent 上下文、恢复，以及机器本地运行时数据之间的确切关系。

这当初为什么这么决定——它现在还成立吗？

在长期项目中最昂贵的一句话是“等等，我们当初为什么那样做？”——每一个新会话、新模型和新队友都会再问一遍，而答案来自逐渐褪色的记忆。Superself 让决策成为一等记录：self decide 携带决策及其 --why，--proposed 标记尚未有人确认的内容，而一次更正会连同其谱系重述该记录，而不是编辑历史。下一个 agent 会读到哪些决策是
当前状态以及它们为何被做出——并停止重新争论那些已经关闭的事项。

这项工作在贡献什么，又被什么阻塞？

任务列表回答的是“有什么要做”。它不回答一个工作单元在贡献什么、实际进展到哪一步，或它为何卡住——而这些恰恰是接手它的人或代理首先需要的问题。在 Superself 中，一个工作单元链接到它所服务的 objective 或 milestone，它的报告附上它们所描述的 commit 作为证据，self work block 记录它在等待什么——一个决定、一个依赖，或某个外部事物——而 process ledger 显示一个代理进程是仍在运行它，还是已经死亡且未报告。接手从该单元自身的记录开始，而不是从上一个会话的 transcript 开始。

“完成”如何保持诚实？

Transcript 文本不是规范状态，代理说“完成”不是证明，自主性不是在没有边界的情况下行动的许可。

self work done 拒绝空洞的声明：只有当报告携带 commit 或 artifact，或者 done 本身陈述了可验证发生的事情时，结果才会关闭。声明的标准会门控该声明，直到每一项都被证据覆盖。报告会自动附上项目的 HEAD commit，附上的 artifact 会根据被摄取的内容进行 digest 校验，并且工作单元的结果一旦记录就不可变——更正会连同其 lineage 重述它，而不是编辑历史。

公司级目标如何展示其进展？

进展由结果评判，而不是由动作评判。一个 goal 分解为按时间盒划分的 objectives；objectives 携带 milestones，其退出标准必须每一项都被证据覆盖，milestone 才算作达成；工作单元链接到它们所服务的内容，因此在每个项目内，从 goal 一直到推动它的 commit 的链条在两个方向上都是可读的。一个 workspace 作用域的记录会在每个项目的上下文中呈现，这就是一次性设定的方向如何到达每一个必须遵循它的项目和代理。

随着项目增长，上下文如何保持小？

状态会为公司存续的整个生命周期而累积；上下文窗口则不会。因此每条记录都携带一个 placement——scope、priority 和 exposure——它决定该记录是渲染为全文、一行索引，还是仅作为一个搜索指针，而 retention caps 以上下文 token 为单位限制始终渲染的集合。增长会把细节降级到 self search，而不是掩埋代理所读取的上下文，降级会记录原因，而提出降级的代理会等待一个人来确认。一个成熟的项目被构建为无需对其自身历史进行超大转储即可恢复——让这种选择在每个作用域都可靠，是路线图 Phase 2 的退出条件。（原始状态动词今天已强制执行这些上限；预设动词尚未受上限门控。）

它强制某种方法论吗？

不。每个动词之下只有一种记录类型——一个带有文本、自由标签、类型化链接和 placement 的实体——而预设动词（goal add、decide、work add 等等）是一个用户可编辑的别名表中的行。
self alias add  将贵公司实际使用的任何标签变为一等动词；self state 记录预设未命名的任何内容。你的词汇、节奏和流程仍归你所有——Superself 对状态进行版本控制，而非方法论。

目前哪些功能可用？

- 持久状态。 目标、决策、约定、目的、里程碑和工作折叠为一个已放置的实体记录，作为仅追加日志中的类型化事件；每个事件都会重新折叠规范视图，并作为工作区自身 git 历史中的一次提交落地。
- 跨会话接续。 self context、self work show 和 self search 为智能体提供当前状态的生成视图，以及进入完整历史的拉取路径；AGENTS.md 和 CLAUDE.md 中的受管块教会终端智能体加载并维护它。
- 成果链接与证据。 工作对目的和里程碑有所贡献；完成是一种判断，其主张必须携带证据，且声明的标准会对其进行把关，直到每项标准都被覆盖。
- 流程账本。 工作单元映射到运行它的智能体进程，其存活状态在读取时判定；合并控制有意留给 GitHub PR 审查和 CI。
- 可检查视图与同步。 self view 渲染工作区、每个项目、工作、决策、事件和产物的只读 HTML 页面；显式的 git 支持同步可在机器之间携带存储。

命令级清单将上述每一项陈述为针对当前 CLI 的可验证主张。

哪些尚未完成？

- 项目上下文尚未能可靠地按工作区、项目、工作、尝试、领域、风险和指令范围进行界定和选择。
- 自然语言意图尚未通过一个稳定的公共契约编译为目的、工作图、策略和尝试。
- 没有任何东西跨项目调度工作；派发是由人或会话启动智能体，而跨优先级、依赖、预算、容量、失败和完成的完整循环尚未得到验证。
- 扩展和 MCP 能力注册表仍是一个设计方向，而非已发布的通用插件运行时。
- 查看器目前是只读的。它尚未成为用于指导、批准、中断和观察公司执行的对话界面。
- 完整路径——一个人工成果、自主规划与执行、从失败中恢复、有证据支持的完成，以及仅对重大判断进行升级——尚未被证明为一个稳定的产品循环。

命令界面比已完成的产品循环更广，因为该项目正在自下而上地构建并自用其可靠性原语。

这正在构建什么样的循环？

Superself 旨在将一个人工指令转化为持久、可检查的执行循环：

human intent
↓
durable directive, goal, and constraints
↓
scoped context and executable work
↓
policy, priority, dependency, capacity, and approval gates
↓
agent 与 MCP 能力执行
↓
恢复、验证与证据
↓
规范项目状态与以异常为中心的报告
↓
只有重大判断才返回给人类

下面的路线图按运营成果组织，而不是按发布日期组织。它陈述的是方向，而不是兼容性或交付承诺。详细的当前约束、近期能力、退出证据和问题映射位于动态路线图中。

- 阶段 1 — 持久项目状态。 使目标、决策、工作、报告、工件、历史和证据能够在任何会话或工具中存续。保持状态本地优先、可检查且可重建。状态：首个可用的 CLI 基础已发布并正在积极自用。
- 阶段 2 — 每个范围内的有界上下文。 编译稳定的工作区、项目、工作和尝试上下文；为当前操作选择治理决策、约定、依赖项和风险规则。退出：新 agent 无需手动重新简报、无需过大的上下文转储，也不会与治理状态相矛盾，即可恢复成熟项目。
- 阶段 3 — 受治理的自主执行。 将有界意图编译为可执行工作，跨项目调度它，监督尝试，恢复失败，验证输出，并完成其证据和权限门控已满足的工作。退出：一个由人类给出的有界方向即可达到有证据支持的完成，无需持续的人工调度或终端监督。
- 阶段 4 — 可组合的公司能力。 让受信任的扩展通过一个受权限控制的能力契约贡献命名空间化操作，包括 MCP 适配器。退出：公司可以添加领域能力，而无需将其硬编码到 Superself 中或绕过其信任模型。
- 阶段 5 — Company State 操作界面。 将查看器转变为用于指令、批准、中断和实时活动的主要对话界面。退出：一个人可以从一个界面指导并理解一个持续运营的 agent 组织，同时对真正重要的决策保持负责。

谁拥有什么——人还是引擎？

Superself 的自主模型是一种责任分配。

人类拥有：

- 目标、优先级、价值观和组织约束；
- 不可逆、外部、高风险或模糊的决策；
- 批准边界以及 agent 在其中运作的策略；
- 对公司最终行为的问责。

引擎应拥有：

- 将已批准的意图转化为有界工作；
- 例行调度、执行、协调、重试和恢复；
- 检查声明的输出、测试、证据和完成条件；
- 维护规范状态并报告重大变更；
- 当策略要求人类判断时进行升级。

为什么要开放核心？

状态、策略、证据和执行边界是公司做出决策的地方
代理可以知道什么、可以做什么。该层必须可检查、可移植，并且能够在本地运行，而不对代理数量、尝试次数或已连接能力进行计量。

开放核心还为能力构建者提供了一份稳定的操作契约，而不需要每个工具都发明自己的记忆、审批、恢复和证据系统。

常见问题

我的数据存放在哪里？
在你的机器上。工作区存储是它自己的 git 仓库，与你的代码分开，在你使用 self remote add 连接自己选择的远程仓库并用 self sync 推送之前，任何内容都不会离开它。没有账户。

它可以与哪些代理配合使用？
任何读取 AGENTS.md 或 CLAUDE.md 的终端代理——受管区块会教它该协议——以及任何能够运行 CLI 的东西都可以直接读写状态。

当两个会话同时写入时会发生什么？
每个事件都是仅追加 JSONL 日志中的一行，因此并发追加——包括来自不同机器的追加——可以干净地合并。另一个会话持有的工作单元会被披露出来，包括由谁持有以及何时持有，而绝不会被锁定。

聊天记录是状态吗？
不是。只有经断言的记录才会进入日志。聊天记录文本不是规范状态，代理说“完成”也不是证明——完成门禁要求提供证据。

Superself 会决定什么合并到 main 吗？
不会。分支通过 GitHub 拉取请求到达 main；合并控制权被有意交给 PR 审查和 CI。Superself 拥有上下文和工作图，而不是合并门禁。

它的成本是多少？
核心采用 Apache-2.0 许可，完全在本地运行，不对代理、尝试次数或已连接能力进行计量。

我如何开发和验证一个检出？

该仓库为使用 nvm 的贡献者固定 Node 22.20，并使用 pnpm 10。

git clone https://github.com/fxylabs/superself.git
cd superself
nvm use
pnpm install
pnpm typecheck
pnpm test
pnpm build
pnpm structure

当你需要当前命令族、记录形状或由实现拥有的帮助边界时，请使用 CLI 和记录参考。如果你正在自定义渲染后的查看器，请使用查看器主题指南了解受支持的令牌和主题边界。

每个文件放在哪里？

apps/
└─ cli/                   self CLI：状态、上下文、工作以及进程账本

docs/
├─ concepts/              状态、上下文、权限和证据模型
├─ guides/                使用当前 CLI 的面向任务的指南
├─ examples/              端到端操作场景
├─ reference/             当前 CLI 命令和记录参考
├─ viewer-theming.md      受支持的查看器令牌和强调主题
├─ content-planning.md    读者优先的简报和审批标准（韩文；.en 对应版本）
├─ content-quality-review.md  可复用的就绪/已验证门禁（韩文；.en 对应版本）
├─ content-guide.md       生产形式、语言规则和发布前检查清单（ko/en）
├─ maintainers/           分支、版本与发布策略
├─ roadmap.md             当前能力、后续成果与退出证据
└─ strategy/              问题定义与定位决策

ARCHITECTURE.md           分层、单一入口、事件命名空间、固定命名
CONTRIBUTING.md           流程与代码约定

面向读者的内容工作还会加载
.agents/skills/content-quality-gate/SKILL.md。该门禁适用于营销
页面、电子邮件、文档、教程、元数据和说明性媒体：经批准的
简报先于制作，独立的 ready 回执先于
发布。它根据工作对读者的影响而非文件
扩展名来分类。

本仓库包含 CLI 和文档。superselfs.com 网站
以及衡量它的运营任务位于一个单独的部署
仓库中，该仓库从这里读取 docs/ —— 本仓库中没有任何内容
发布网站或运行计划任务。

在更改代码之前阅读 ARCHITECTURE.md，在
提交 issue 或 pull request 之前阅读
CONTRIBUTING.md。

我如何贡献？

- 使用结构化的 GitHub issue 表单提交可复现的 bug、具体的功能
提案和维护工作。
- 在维护者接受相关 issue
并将其分配给你之前，不要提交 pull request。
- 为每个提交签名，以证明
开发者原创证书。
- 根据 SECURITY.md 私下报告漏洞。
- 在提议
版本或标签更改之前，阅读发布策略。

Superself 仅在维护者接受
并分配相关 issue 后才接受实现类 pull request。贡献按 Apache-2.0 许可，
如 CONTRIBUTING.md 所述。

许可证

Superself 根据 Apache License 2.0 许可。