以迭代推动演进

darwin 是一项自托管 AI 开发实验。v0.0.1 基线版本完全由 Claude Code 编写。此后的功能、修复和版本发布，都由当前版本的 darwin 在本仓库内完成。新版本通过独立验收后，就会接手下一轮开发。

开发责任始终由人承担：产品取舍、安全边界和工作授权由人决定；仓库证据无法回答的问题也由人处理；最终结果仍需人来验收。darwin 在这些边界内负责编写实现。基线版本提供固定参照，后续工作则由 git 历史和迭代日志留痕。

内置自演进研究

/self-evolution-research 负责在实现之前选择方向。它会先推进持久化研究待办中的未完成事项；没有积压任务时，才会进行一次有记录、不可随意重抽的加权抽签。候选路径包括同类产品研究、TUI 自检、开放式改进、尚未使用的 Strands SDK 能力，以及可观测性。

研究过程会引用仓库证据或产品一手资料，剔除重复项，再按价值、架构契合度、证据强度、难度和风险评分。只有达到门槛的方向才会进入实现队列。每个方向都会单独交给内置 developer 监督器：新的无头 darwin 子会话完成开发，Host 随后独立检查 diff，并重新执行验收命令。只有通过验收的版本，才会进入下一个方向。

未完成待办，或一次加权研究路径抽签
  → 有证据支撑的研究与评分
  → developer 监督下的实现
  → 独立验收与提交
  → 同步 README / 用户指南 / 架构文档
  → 通过验收的新版本继续研究并开发下一版

这套流程有明确边界，不代表 darwin 拥有产品决策权。工作树不干净、起点无法验证、验收反复失败、前提被证伪，或遇到只能由人决定的产品/安全问题时，整批工作会停止，并把原因写入记录。证据可查阅按日期归档的研究报告和自省报告。

迁移已有设置

在目标项目内运行 darwin import --from claude-code，可只读预览有上限的迁移计划。Linux 上加 --apply 后，只复制支持的提示词型 skills、agents，以及带来源标记的 CLAUDE.md 段落，不会静默覆盖已有内容，也不会写入或启用 hook、MCP、权限策略或信任记录。执行前请查看支持的映射与手动步骤；此命令不导入聊天，也不切换模型供应商。

主要能力

• **清晰的 Ink TUI：**流式 Markdown 回复、文件修改 diff、耗时与 token 消耗、斜杠命令与路径补全、提示词回看和排队、本地 ! 命令，以及有长度上限的状态报告。
• 安全审批模式：default、带分类器的 auto、只读 plan 和显式开启的 yolo；项目级放行规则保存前须完整预览，并可在会话内撤销；拒绝规则在所有模式下生效，包括 yolo。checkout 自带的钩子命令、MCP 服务器和旧式放行规则会一直保留不用，直到你在一个列出它们究竟会运行什么的工作区信任模态框中接受；答案保存在仓库之外，无头运行从不询问。
• **可持续的工作状态：**按项目保存的可恢复会话、只追加轨迹、回放/搜索/分叉/导出、费用记录、可选诊断日志、后台任务，以及由父 agent 按需管理、带精确证据并在回合持久化后提交的项目记忆。
• **扩展机制：**内置及项目/全局 skills、自定义命令、子代理与 workflow DAG 委派、工具 hooks、stdio/HTTP MCP 服务器，并兼容 .agents/ 目录。自定义命令会替换 $ARGUMENTS；若模板没有该占位符，且参数去除首尾空白后非空，则在完整模板后追加两个换行符和参数。详见自定义命令。
• **上下文用量：**运行 /context 可查看当前请求的估算分项；技能目录下面按已注册技能分别显示 token 估算值。它只在调用时计算，不是每回合的实际费用；计数失败显示 not reported，过长列表会截断并标明余数。参见查看上下文开销。
• **自动化接口：**单次文本输出或带版本的 JSON/JSONL；严格选择会话；可限制模型调用次数和上下文卸载；取消或失败时返回非零状态码。
• **多模型支持：**Amazon Bedrock、Anthropic 直连、OpenAI 直连，以及通过 Bedrock Mantle 使用 OpenAI 兼容模型；会话中可切换模型和思考强度。

darwin 不会另写一套代理循环。它沿用 Strands SDK 的循环，只负责组装 SDK 模型、interventions、plugins、conversation manager 和工具。维护者可在架构决策中查看设计依据。

安装与启动

需要 Node.js 22.0+、npm，以及所选模型供应商的凭证（默认使用 AWS）。

npm install -g strands-darwin

npm 包名是 strands-darwin，安装后的命令是 darwin。包的 postinstall 脚本会用 patch-package 应用 darwin 固定的 Strands SDK 补丁，因此不要加 --ignore-scripts——跳过了这一步的安装会在启动时被拒绝，并给出指向这条修复路径的提示。不支持 pnpm add -g：pnpm 默认拦截依赖的构建脚本，即便放行，它的隔离目录布局也会把 SDK 放在 patch-package 找不到的位置。

此后可以在任意目标仓库中直接运行 darwin；当前工作目录会被视为项目根目录：

cd /path/to/your-project
darwin
darwin --resume
darwin --resume <id>        # 查看 id：darwin sessions
darwin --session <id>
darwin doctor               # 离线只读诊断：配置、MCP、技能、hook；发现问题时退出码 1
darwin permissions test 'bash:pnpm *'  # 检查项目已记录调用，不改权限
darwin mcp login <name>     # 为配置了 "oauth": true 的远程 MCP 服务器做 OAuth 登录；令牌存于 ~/.darwin/mcp-auth/
# TUI：/permissions test bash:pnpm *（仅当前会话，忙碌时也可用）
darwin --help               # 用法语法；darwin --version 打印版本

开发 darwin 本身

克隆仓库并使用 pnpm（lockfile 是 pnpm 的；pnpm install 会自行应用 SDK 补丁）：

git clone https://github.com/xiehust/strands-darwin.git
cd strands-darwin
pnpm install
pnpm start                  # 直接运行 TypeScript 源码，无需构建
pnpm build                  # 输出 dist/（CLI、内置 skill 和生成的 patch-package 补丁文件）

pnpm build 之后运行 pnpm add --global . 可以把全局 darwin 链接到当前克隆目录；之后请保留该目录，修改源码后重新运行 pnpm build。TUI 测试使用的 node-pty 是原生开发依赖，已列入 pnpm-workspace.yaml 的构建白名单。若添加新的原生依赖，也要更新这份白名单。

配置模型

模型和供应商只读取 ~/.darwin/config.json。文件不存在时，darwin 使用内置 Bedrock 模型目录。最小 Bedrock 配置如下：

{
  "provider": "bedrock",
  "model": "global.anthropic.claude-opus-5",
  "region": "us-west-2",
  "permissionMode": "default"
}

Bedrock 使用标准 AWS 凭证链。模型 ID 必须是 us.、eu.、apac. 或 global. 等推理配置文件 ID，不能直接填写 anthropic.*。直连供应商默认读取 ANTHROPIC_API_KEY 或 OPENAI_API_KEY；直连 Anthropic 还支持通过 baseUrl（或 ANTHROPIC_BASE_URL）接入任何兼容 Messages API 的端点。

多模型切换、各供应商字段、Bedrock Mantle、缓存、思考强度、上下文限制和全部会话设置，见入门与模型供应商和配置与上下文。

日常使用

用 /list-agents 或离线 CLI darwin list-agents，可以跨项目查看当前 HOME 中本机仍存活的会话租约持有者；CLI 不需要配置模型供应商。这只是只读查看，不提供通信能力；/agents 仍然列出本进程的子代理派发。详见范围与限制。

需要实际通信时，先用 /collaborate list，再输入 /collaborate send <endpoint-uuid> <文本>。 同一规范项目路径的会话会在空闲时自动接收并回复；不同项目只需用户亲自执行一次 /collaborate confirm <pending-id> --persist，双向协作关系重启后仍有效。 用 /collaborate pending|relations|revoke <pair-id>|off 查看、撤销或关闭；独立 CLI darwin collaborate 支持相同子命令。主模型只有 peer_discover、peer_send，不能确认信任。 消息不构成用户授权或用户记忆引文。见操作流程、限制与隐私。

/                       列出命令、skills 和自定义命令
@src/                   补全工作区路径（只插入路径文本）
!pnpm test              运行由用户主动输入并授权的本地命令
/developer <requirement>
/self-evolution-research
/help                   查看本地命令、输入语法和按键说明
/init                   请模型为当前项目创建或改进 AGENTS.md
/review [focus]         审查当前改动中的缺陷和测试缺口
/review --commit <SHA>  审查指定的 40 位十六进制提交
/copy                   把最近一条已完成回答复制到剪贴板（OSC 52，SSH 下可用）
/rewind                 从已完成提示词分支对话（工作区不变）
/tangent                为一次旁支提问给对话加书签；再输入 /tangent 即返回
/goal <条件>            持续工作直到条件成立：每个完成的回合后由小模型检查一次，最多自动续跑 5 次；/goal 查看，/goal off 清除

按 Ctrl+R 可搜索当前项目的提示历史（输入文字筛选，按 Ctrl+R/Up/Down 切换结果，按 Enter/Tab 接受，按 Escape 取消）；忙碌时按 Ctrl+C 取消，按 Ctrl+B 展开或收起工具详情，使用 /exit 或 Ctrl+D 退出。编辑输入时，Ctrl+Home/Ctrl+End 跳到整份草稿的开头／结尾；普通 Home/End 和 Ctrl+A/Ctrl+E 仍只移动到当前显示行的开头／结尾。Alt/Ctrl+Left/Right 或 Alt+B/Alt+F 按词移动光标，Alt+Backspace/Alt+D 删除光标前／后的一个词，Ctrl+_（或 Ctrl+-）可撤销最近一次 Ctrl+K/Ctrl+U、Ctrl+W 或 Alt 系列的删词操作。Ctrl+Y 会在当前光标处插入最近剪下的文本，同一草稿内可重复使用，不经过剪贴板；剪切恢复的上限与清空规则见使用指南。Ctrl+S 可暂存一份未提交草稿，保留光标位置和附图；输入框为空时再按一次即可取回。不会覆盖或自动发送，期间可以提交其他问题；切换到新会话或退出时丢弃（草稿暂存规则）。输入框为空且空闲时，连按两次 Esc（第二次在 500 ms 内）会打开 /rewind 选择器，效果与输入 /rewind 完全相同；此时单按一次 Esc 不做任何事。模型发起的工具调用仍会经过当前审批模式；! 命令由你亲自输入，因此不走模型工具审批。darwin 启动的每个进程——模型的 bash shell 与后台任务、你的 ! 命令、hook 命令和 stdio MCP 服务器——环境中都带有 DARWIN=1（你已导出的 DARWIN 原样保留），脚本和 hook 由此可以判断自己运行在代理之下。

想在切到别处时被叫回来，可在 ~/.darwin/config.json 中设置 "terminalBell": true（响一次终端铃）和／或 "terminalNotify": true（写一条 OSC 9 桌面通知序列，iTerm2、kitty、Ghostty、WezTerm 和 foot 会弹出通知，其他终端静默忽略）；二者都在权限提示等待时和回合结束时触发，默认均为关闭。iTerm2 需开启 "Send escape sequence-generated alerts"；tmux 需要 set -g allow-passthrough on。详见配置与上下文。

/review 请模型检查暂存、未暂存的改动及相关未跟踪文件，按优先级报告有证据的缺陷，并单列测试缺口。可选 focus 保持为字面文本。/review --commit <40-hex-SHA> 则要求审查指定提交与父提交的差异（根提交与空树比较）及周围代码／测试；无效参数在本地提示用法，缺失的对象须如实说明。提示要求未经另行请求不要修改文件或提交，但不会强制只读，也不改变权限模式。内置命令现在占用 /review；原来使用该斜杠名称的自定义命令或 skill 需要改名，例如 audit。详见审查改动。

无交互运行方式如下：

darwin -p "inspect this project"                         # 回复写 stdout，进度写 stderr
darwin -p "inspect this project" --output-format json
darwin -p "inspect this project" --output-format stream-json

TUI、无头模式、结构化输出、消息队列、shell 命令和后台任务的完整约定，见使用 darwin。

主代理模型流连续 600 秒没有事件时会明确报错，不自动重试；思考事件也会重新计时，权限、工具和重试等待不计入。根级 streamIdleTimeoutSeconds 可调整秒数（0 关闭）；详见范围与取消语义。

可选云记忆

AgentCore Memory 默认关闭，与模型供应商独立，原有本地项目记忆不变。它提供受权限控制、仅主代理可用的 episode/reflection 检索、用户明确确认的跨项目偏好，以及单独启用的手动预览、发送或项目授权自动上传新回合的有界原始工具内容，涵盖任意工具/MCP 的文本参数与结果；其中可能含有秘密，不保证保密。偏好采纳、上传和删除控制仅限用户亲自提交的 TUI 命令，独立 cloud-memory CLI 只读。上传省略全部助手文本。/cloud-memory auto 仅为当前项目的新回合持久化授权；/cloud-memory manual 停止尚未发送的自动任务。默认每 UTC 日 500 次尝试/100 MiB，自动接受的本地请求体保留七天，分区幂等回执长期保留。根级 upload: auto 不构成授权。用户命令 discard-legacy 先预览本地旧格式批次，再以清单哈希确认，不删除云记录。

在 TUI 输入 /setup-agentcore-memory 开始引导配置。Darwin 会先读取完整指南，通过权限检查只读查看现有 ~/.darwin/config.json，再运行离线 darwin doctor、本地 darwin cloud-memory status 和通过 SDK 有界只读检索的 darwin cloud-memory preferences。已配置且基本检查通过就无需重复设置、询问 actor 或重启；空记录也算读取成功，但不证明提取或写入权限。只有缺失/禁用后的配置分支才询问 actor 和默认值；检查失败或受阻时请求针对性修复确认，不自动重置。参数不代表修改授权。优先复用兼容资源；启动配置不代表授权上传或采纳偏好。运行时通过固定版本的官方 @aws-sdk/client-bedrock-agentcore 读写，不再依赖 AWS CLI 可执行文件。旧 cliPath 仍校验格式，但会忽略并提示移除。可选的 agentcore CLI 只用于独立的基础设施管理；其 schema/import 尚不能完整保留自定义命名空间键和模板，因此暂不导入现有资源。中文指南列出了准确模板、配置、IAM、/cloud-memory 命令、隐私边界和可选合成数据验证。本次实现未运行真实 Memory 服务测试。

文档

• **用户指南：**安装、供应商、日常操作、配置、状态、安全、扩展、命令参考、限制和开发说明。
• **架构：**实现变更必须遵守的关键约定。
• **研究待办与研究报告：**自演进方向的证据与排序。
• **迭代日志：**受监督的实现批次与独立验收结果。
• **自省报告：**基于轨迹复盘会话，并可将改进方向写入研究待办。

项目状态

darwin 仍处于实验阶段，命令会直接在本机执行，并不提供沙箱。模型工具调用的安全边界是权限门。用于敏感或无人值守的任务前，请先阅读限制与开发。

许可证

ISC