chiliarch 0.1.0__tar.gz

chiliarch-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+web/node_modules/
+web/coverage/
+web/.vite/
+data/
+logs/
+chiliarch.toml
+*.db
+*.db-shm
+*.db-wal
+*.log
+*.jsonl
+*.egg-info/
+.env
+.DS_Store
+src/chiliarch/static/*
+!src/chiliarch/static/.gitkeep

chiliarch-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

chiliarch-0.1.0/AGENTS.md

@@ -0,0 +1,16 @@
+# chiliarch 开发规范
+
+- 与用户使用简体中文交流。Python 代码必须包含类型注释，兼容 Python 3.11–3.13。
+- 修改前先阅读现有实现；使用 Context7 核对库/API 文档，复用已有代码，避免硬编码部署地址、密钥、模型名称和机器路径。
+- Python 使用 uv 和 uv.lock；前端使用 pnpm 和锁文件。保持依赖、配置与文档一致。
+- 所有 agent 连接必须由 agent 主动出站建立。服务端不得主动连接 agent、发起反向回调或通过地址接管机器。
+- WS、SSE＋POST、长轮询共用协议、身份、消息队列和幂等入口；不能为每种传输另写业务规则。
+- `chiliarch.protocol` 不得依赖服务端、数据库、模型 SDK。协议版本独立于软件版本；协议变更必须同步 Schema、文档与行为测试。
+- 用户操作、总管工具、下级请求必须经过统一操作服务。不能让 prompt、工具重试或下级身份绕过审批、吊销和参数校验。
+- 消息 ACK 表示持久接收，不代表执行成功。不承诺外部副作用恰好一次；未知执行结果不能自动重新执行。
+- 密码、API Key、agent 凭证不写入日志或模型上下文。只有服务商公开返回的思考内容/摘要可以展示，签名与密文回放数据单独保存。
+- 新增或修改行为必须同步 README、docs、配置说明与有意义的测试；测试应验证状态、网络行为和副作用，禁止通过搜索源码字符串代替功能测试。
+- 验证命令：`uv run ruff check .`、`uv run ruff format --check .`、`uv run mypy`、`uv run pytest`；前端在 web 下运行 `pnpm typecheck`、`pnpm test`、`pnpm build`。
+- 发布前使用版本脚本同步版本，校验 tag、包元数据与 CHANGELOG；构建产物必须包含 WebUI 和协议 Schema。
+- Git 提交使用 GPG 签名；签名失败时请求用户刷新密钥，不退回无签名提交。不默认推送或发布。
+- 当前继续完善 v0.1.0；按用户最新要求，每完成并验证一个独立开发块后签名提交，不默认升级版本。

chiliarch-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# CHANGELOG
+
+## v0.1.0 初版框架
+
+chiliarch 提供由 agent 主动出站连接的统一调度平台，将手动管理、总管 AI 和下级请求纳入同一个操作与审批体系。
+
+- **统一连接与投递**：一次性注册码兑换可吊销凭证，支持 WS、SSE＋HTTP POST 和长轮询；持久消息队列、心跳、重连与幂等处理区分消息接收和任务执行结果。慢接收与延迟 ACK 时按消息独立退避，避免重复帧堆积阻塞任务完成和后续通信。
+- **目标与持续协作**：持久目标保存约束、验收条件、任务依赖和产物；前置任务验收通过后自动派发后续工作，返工保留独立尝试和历史结果，可连同评审与产物引用交给另一个 agent 接手。任务终态与下级来信推动总管在原目标会话继续协调，积压事件批量处理、等待审批时排队；用户停止后暂停自动唤醒；临时模型故障有界退避核查，失联与进度停滞主动生成协调通知。服务重启只核对最新中断的任务与操作结果，不越过后来的停止。目标页统一呈现分工、依赖、验收和交付，支持搜索与待处理筛选，并将下级请求和包裹审批关联到目标；取消目标同步撤销相关待执行审批，吊销身份的远端停止状态保持明确。
+- **同伴通信与材料交付**：agent 可直接发现同伴、发送有可信身份的私信并参与目标讨论，回执区分送达、读取和处理；任务收件箱、稳定请求 ID 和消费游标支持离线恢复。私信可明确唤醒托管 agent，普通回信不自动连环唤醒；协作等待检测任务和工作目录形成的循环。跨机器产物使用分块传输、成员范围与 SHA256 校验，WebUI 提供讨论、私信、回执与等待关系。Codex／Claude 可续接平台创建的最近成功原生会话，失败或未知工作不能绕过核查。
+- **执行感知与工作区协调**：区分守护连接在线、会话等待领取、托管忙碌与执行受阻，并提供中文原因与本机处理指引；同一工作目录的托管任务跨身份互斥，清理结果未知时持久隔离，核查后可通过本机命令解除。POSIX 取消确认整个进程组无运行成员，三系统启动失败完整释放已取得的资源。
+- **总管 AI**：支持 Chat Completions、Responses、Anthropic Messages，按事件时间顺序穿插展示正文、公开思考内容、工具调用和执行结果，刷新与流式重连保持顺序；输出长度默认由服务端决定，可设置默认 200k 的上下文窗口，达到 90% 自动压缩并保存接续摘要，完整聊天记录与审批边界保留，界面显示占用与压缩进度；不再设置固定工具轮次、上下文消息数及全局并行运行上限；ask、auto、yolo 模式同样约束下级请求的处理。
+- **WebUI**：精简的单用户密码登录与明暗主题按钮，暗色使用炭灰与暖白层级；导航可收起并记住选择，配置表单居中；总管对话提供用户气泡、浮动输入区、折叠思考与工具、短动画和“回到最新”，支持 Enter 发送、Shift + Enter 换行；右侧会话列表默认收起，鼠标靠近自动显示，可固定展开、重命名和删除，首次成功问答后由模型自动命名并保留手工标题；新会话入口常驻，审批直接放在工具调用下方；Agents 管理使用机器卡片、待处理徽标、独立配对弹窗和详情驾驶舱，未连接时提示居中显示，提供任务派发、请求处理与凭证管理。
+- **Agent 接入与协作**：Windows、macOS、Linux 的当前用户共享守护进程先发现复用、检查健康，再登记独立 agent；默认登录后自启动，MCP 通过本地标识使用已有连接。Codex App、Codex CLI、Claude Code 可通过 stdio MCP 领取调度、汇报进度与结果、联系总管及申请跨 agent 协作；本地托管 runner 检查原生成功终态，在取消或超时后清理进程树。只读下级请求按查询规则处理，回复保留关联身份，离线队列与任务幂等支持安全恢复；接入文档提供可直接复制给 agent 的简短提示词，通过 GitHub 原始文件地址读取独立接入指南，由 agent 检查环境、询问配置并接入自己。
+- **原生设置继承**：Codex 托管执行使用本地 app-server stdio，Claude Code 保留 print JSONL；沿用原生模型、服务商、认证、权限、指令、MCP、skills 和 hooks，只追加任务专用、名称唯一的 mailbox MCP。runner 的模型、沙箱、审批模式和工具规则由原生配置管理。原生审批和用户输入尚无跨平台回复桥，必须交互且无法继续时明确受阻或失败；平台审批不改变原生权限。三系统自启动配置保存非秘密配置目录环境变量，已有服务需重新安装并重启才能刷新，复用健康进程不会自动读取新终端环境。
+- **扩展与运行**：独立协议模型和 JSON Schema、统一操作扩展接口及出站客户端；SQLite 持久存储、跨平台配置原子保存与热重载、结构化日志轮换。平台和守护进程的 HTTP 优雅关闭等待可配置，默认 15 秒，避免活跃 SSE 请求无限阻塞后续资源清理。在线备份包含已提交 WAL 数据，校验后原子发布独立快照，拒绝覆盖已有文件，可显式选择实际运行的数据库。OpenCode、Undefined 及其他厂商插件保留扩展边界。
+
+---

chiliarch-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Null <pylindex@qq.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chiliarch-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: chiliarch
+Version: 0.1.0
+Summary: An outbound-only agent orchestration platform with a first-class AI supervisor.
+Project-URL: Repository, https://github.com/69gg/chiliarch
+Project-URL: Documentation, https://github.com/69gg/chiliarch/tree/main/docs
+Author-email: Null <pylindex@qq.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,orchestration,webui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: aiosqlite<1,>=0.20
+Requires-Dist: anthropic<1,>=0.49
+Requires-Dist: anyio<5,>=4.6
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: filelock<4,>=3.18
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: jsonschema<5,>=4.23
+Requires-Dist: mcp<2,>=1.30
+Requires-Dist: openai<3,>=1.68
+Requires-Dist: packaging>=24.2
+Requires-Dist: pydantic<3,>=2.10
+Requires-Dist: sqlalchemy[asyncio]<3,>=2.0.38
+Requires-Dist: tomli-w<2,>=1.2
+Requires-Dist: uvicorn[standard]<1,>=0.34
+Requires-Dist: websockets<17,>=14
+Description-Content-Type: text/markdown
+
+# chiliarch
+
+连接、管理与统一调度 agents 的平台。内置 Chiliarch AI 总管，提供手动管理、持久对话、工具调用和 ask / auto / yolo 审批模式。
+
+所有连接都由 agent 主动出站发起，服务端永远不主动连接 agent。v0.1.0 提供平台框架、独立协议、跨平台共享守护进程、MCP 会话桥和本地 CLI 执行器。
+
+## 支持的 agents
+
+| Agent       | 当前会话接收调度、汇报与协调    | 无人值守执行                  | 接入文档                                  |
+| ----------- | ------------------------------- | ----------------------------- | ----------------------------------------- |
+| Codex App   | stdio MCP，当前会话主动领取任务 | 使用同机独立 Codex CLI runner | [Codex App / CLI](docs/agents/codex.md)   |
+| Codex CLI   | stdio MCP                       | 本机 `codex app-server` stdio | [Codex App / CLI](docs/agents/codex.md)   |
+| Claude Code | stdio MCP                       | `claude --print`＋JSONL       | [Claude Code](docs/agents/claude-code.md) |
+
+接入文档开头有可直接复制给 agent 的简短提示词，无需预填参数；agent 会通过 `raw.githubusercontent.com` 读取 [自助接入指南](docs/agents/onboarding.md)，主动询问缺少的配置并把自己接入平台。详见 [Agent 接入与协作](docs/agents/index.md)。MCP 会话接入支持领取任务、进度与结果、向总管提问、查询其他 agents 和申请协作调度；不会自动唤醒 Codex App 的空闲会话。本机共享守护进程先发现复用、再配对登记，默认当前用户登录后自启动；支持 Windows、macOS、Linux 的 MCP 与托管运行，CLI runner 默认创建新会话，也可明确续接 Chiliarch 创建的最近成功会话。OpenCode、Undefined 保留 [协议和扩展接口](docs/extensions.md)，尚未实现对应适配器。
+
+托管执行沿用本机 Codex／Claude 的模型、服务商、认证、原生权限、项目指令、MCP 和其他原生配置；只为当前任务额外添加一个名称唯一的 Chiliarch mailbox MCP。runner TOML 负责程序、固定工作目录、超时和输入输出限额。Codex 的 app-server 是本地子进程，不控制桌面 App。当前尚无跨平台原生审批或用户输入回复桥；必须交互且无法继续时任务会明确受阻或失败，平台 ask/auto/yolo 不会改写原生权限。runner 配置字段见 [配置说明](docs/configuration.md#本机-runner-与原生配置)。
+
+仓库地址为 [69gg/chiliarch](https://github.com/69gg/chiliarch)。
+
+## 快速开始
+
+支持 Python 3.11、3.12、3.13；开发默认使用 3.13。Python 由 [uv](https://docs.astral.sh/uv/) 管理，前端由 pnpm 管理。
+
+默认从 PyPI 安装，前端构建产物随 Python wheel 和 sdist 发布，无需 Node 或 pnpm：
+
+```bash
+uv tool install chiliarch
+chiliarch init
+chiliarch serve
+```
+
+`init` 交互设置单用户登录密码并创建 `chiliarch.toml`；POSIX 权限为 0600，Windows 继承配置所在目录的 ACL，请保存在当前用户私有目录。配置保存支持三系统的原子替换与热重载。浏览器访问 `http://127.0.0.1:8000`。需要其他机器访问时，在配置中修改监听地址和公开地址，或使用 `serve --host <监听地址>`；HTTPS 可选。
+
+停止平台或本机守护进程时，默认等待 HTTP/SSE 请求结束最多 15 秒，随后进入资源清理，避免长连接无限阻塞关闭。平台使用 `server.graceful_shutdown_seconds`，守护进程使用 `daemon.json` 中的同名字段；修改后重启生效。该期限不限制后续 agent 任务及进程树清理，详见 [部署文档](docs/deployment.md)。
+
+源码开发与本地构建见 [开发、测试与发版](docs/releasing.md)；用户部署见 [部署文档](docs/deployment.md)。
+
+在线备份可运行 `chiliarch backup --output ./backups/platform.db`，命令校验并保存包含已提交 WAL 数据的独立 SQLite 快照，不覆盖已有文件。数据库存在待重启配置变更时，使用 `--database` 指定实际运行的数据库；配置、密钥环境和 agent 状态库需另行保管。详见 [备份与恢复](docs/deployment.md#备份与恢复)。
+
+首次登录后，在“配置”页面设置模型 API、模型名称、地址和 API Key；也可通过环境变量提供密钥，例如 `CHILIARCH_MODEL__API_KEY`。未配置模型时，手动管理仍然可用，总管不会生成假回复。
+
+## 使用总管对话
+
+页头提供“新会话”入口，右侧会话列表默认收起，桌面鼠标移到右边缘自动显示，也可点击按钮固定展开；每条会话可重命名或删除。首次成功问答后由当前模型自动生成标题，手工标题不会被覆盖，命名失败不影响回答。用户消息靠右显示，Chiliarch AI 的正文、公开思考和工具调用按事件时间顺序穿插呈现，刷新和重连后保留原顺序，思考与工具详情可以折叠；需要许可的操作可在对应工具下方批准或拒绝。
+
+底部输入区随内容增高：Enter 发送，Shift + Enter 换行，也支持 Ctrl / ⌘ + Enter；输入法确认候选词时不会提交。阅读历史时不抢走滚动位置，点击“回到最新”或发送消息后继续跟随输出。关闭页面后总管仍在后台运行。
+
+模型输出长度默认由服务端决定；“配置”中可设置模型上下文窗口，默认 200k tokens，达到 90% 后自动压缩并继续工作。页面显示上下文占用与压缩状态，完整聊天和工具记录保留；工具轮次、消息条数和全局并行运行不再设固定上限。原生 Anthropic API 的必填输出参数及压缩机制见 [模型与总管行为](docs/models.md#上下文窗口与自动压缩)。
+
+左侧导航支持收起，并记住当前浏览器的选择；配置表单在工作区内居中。主题按钮可切换跟随系统、浅色和深色；暗色采用炭灰背景、暖白文字及中性表面层级。抽屉、消息和折叠动画遵循系统“减少动态效果”设置。更多说明见 [模型与总管行为](docs/models.md)。
+
+## 连接 agent
+
+在 Agents 管理页面点击右上角“添加 agent”，创建一次性注册码，然后在 agent 所在机器执行（替换占位符）：
+
+```bash
+chiliarch daemon status
+# 首次接入：chiliarch daemon install；已安装但未运行：chiliarch daemon start
+chiliarch agent pair --server <平台HTTP或HTTPS地址> --name <agent名称> --adapter codex-app --agent codex-main --state /绝对路径/私有目录/agent.db
+chiliarch agent config --host codex-app --agent codex-main
+chiliarch agent doctor --agent codex-main
+```
+
+将生成的 MCP 配置合并到原生 agent 配置中；Codex CLI 使用 `codex`，Claude Code 使用 `claude-code`。当前会话通过 MCP 主动领取任务，自动执行则按接入文档配置本地 runner。客户端复用原生 agent 的安装与登录，不上传原生认证文件；注册码交互输入，长期凭证保存在本地状态库。默认不覆盖已配对状态。`agent pair` 先确认本机守护进程健康，再配对并登记；多个 agent 保留独立身份与队列。MCP 配置只携带本机标识，不携带平台凭证。管理、自启动和独立运行方式见 [本机守护进程](docs/daemon.md)。
+
+只想验证协议、不运行真实厂商 agent 时，可使用原有模拟客户端：
+
+```bash
+chiliarch pair --server <平台HTTP或HTTPS地址> --name <agent名称> --state ./agent.db
+chiliarch demo-agent --state ./agent.db
+```
+
+注册码交互输入；长期凭证只保存在本地状态文件，不在终端显示。`demo-agent` 只模拟进度和结果，不运行命令、不操作真实厂商 agent。客户端优先 WS，其次 SSE＋HTTP POST，最后长轮询，支持持久去重、离线队列和重连。
+
+接收或落盘较慢时，未确认消息按条退避重投，避免重复帧积压影响新任务、回复和进度；重连后继续使用原消息 ID 恢复投递。
+
+## 目标与多 agent 协作
+
+在“目标”页面创建需要持续推进的工作，记录约束和验收条件；也可以直接让 Chiliarch AI 创建目标并分工。每项任务可关联目标、前置任务和自己的验收要求。前置任务只有执行完成且验收通过后，后续任务才会投递；产物可登记为提交、PR、报告或其他引用，随依赖上下文交给后续 agent。
+
+目标列表支持按名称、说明或任务内容搜索，按状态筛选，也可只看需要处理的目标。页面区分待验收、待返工、依赖等待、agent 离线、会话未领取、待请求和待审批；历史尝试不会误算成当前故障。重试弹窗可选择接手 agent，并保留执行前的核查说明。
+
+任务完成、失败、中断，以及用户更新目标会进入持久协调队列，自动交给总管继续处理。任务相关来信回到原目标会话；会话正在运行或等待审批时，新事件排队等待，同一会话积压的协调事件会合并处理。总管的回复不会反过来反复唤醒自己。模型暂未配置时先保留事件；临时模型连接或限流故障按配置退避开启新的核查轮次，用户停止和不可恢复失败仍需明确继续。任务停滞或 agent 长期失联会通知总管核查，不把离线当作已停止。
+
+执行成功与验收通过分别记录。需要返工时创建新的尝试并保留旧结果，也可选择另一个 agent 接手；交接携带原结果、评审、产物引用与恢复说明，保留原目标和依赖关系。仍在执行或取消未确认的任务不能直接转交。目标只能在有效任务均验收通过后完成。服务重启后先将最新中断的协调轮次与实际任务状态核对，不重放旧工具调用，也不越过后来的用户停止。agent 心跳区分等待领取、忙碌和工作区阻塞；相同实际目录的托管任务互斥执行。详细工具、恢复流程和保证边界见 [目标、依赖与验收](docs/coordination.md)。
+
+## 同伴通信与共享材料
+
+导航“协作”提供讨论组、私信、回执和“谁在等谁”。agent 可以直接发现同伴、交换消息并查询讨论，普通通信不需要总管逐条传话；ask 下状态变更仍需批准。消息区分已送达、已读和已处理，托管收件箱按任务隔离，稳定请求 ID 与消费游标支持重启恢复。
+
+明确设置 `wake=true` 的私信会为托管 agent 创建响应任务，继承目标与会话；普通回复默认不再唤醒，避免相互调用。`dispatch_task(continue_task_id=...)` 可安全续接 Codex／Claude 最近成功的受管会话；manual App 仍需主动读取 MCP 消息。协作等待会检查依赖环与执行资源冲突；相同工作目录仍保持互斥。
+
+共享产物经已有出站通道分块上传、下载，带成员访问范围、不可变大小/哈希清单和落盘校验。文件内容不会作为总管工具结果展开；可将 `chiliarch:artifact:<ID>` 登记为任务交付引用。详见 [横向通信与协作](docs/collaboration.md) 和 [共享产物](docs/artifacts.md)。
+
+## 总管模式
+
+| 模式 | 查询 | 状态变更 |
+|---|---|---|
+| ask | 直接执行 | 每项请求用户批准 |
+| auto | 直接执行 | 依据风险判断；高风险必须询问 |
+| yolo | 直接执行 | 总管自主决定 |
+
+下级 agent 的请求也遵循相同模式。总管不能批准自己的待审批操作；用户在管理页面直接提交的操作视为该次授权。身份验证、吊销、超时和本机执行边界在所有模式下生效。
+
+## 开发与发版
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv run pytest
+pnpm --dir web typecheck
+pnpm --dir web test
+pnpm --dir web build
+uv run python scripts/bump_version.py 0.2.0 --dry-run
+uv run chiliarch schema --output src/chiliarch/protocol/schema.json
+uv build
+```
+
+版本升级脚本同步 pyproject、uv.lock 和前端元数据；CHANGELOG 需要按最终用户行为单独撰写。`v*` tag 流水线验证、构建并通过 PyPI Trusted Publishing 发布，配置步骤见 [发版文档](docs/releasing.md)。
+
+## 文档
+
+- [部署、初始化与维护](docs/deployment.md)
+- [配置、热重载与日志](docs/configuration.md)
+- [架构与保证边界](docs/architecture.md)
+- [目标、任务依赖、产物与验收](docs/coordination.md)
+- [同伴消息、讨论、唤醒与任务等待](docs/collaboration.md)
+- [跨机器共享产物与访问范围](docs/artifacts.md)
+- [本机共享守护进程、登录自启动与维护](docs/daemon.md)
+- [agent 协议与 JSON Schema](docs/protocol.md)
+- [Agent 接入、安装提示词与协作工作流](docs/agents/index.md)
+- [供 agent 读取的自助接入指南](docs/agents/onboarding.md)
+- [Codex App / Codex CLI](docs/agents/codex.md) · [Claude Code](docs/agents/claude-code.md)
+- [扩展操作与参考客户端](docs/extensions.md)
+- [模型兼容与总管行为](docs/models.md)
+- [开发、测试与发版](docs/releasing.md)
+- [CHANGELOG](CHANGELOG.md) · [开发规范](AGENTS.md)
+
+作者：Null · pylindex@qq.com。MIT License。

chiliarch-0.1.0/README.md

@@ -0,0 +1,141 @@
+# chiliarch
+
+连接、管理与统一调度 agents 的平台。内置 Chiliarch AI 总管，提供手动管理、持久对话、工具调用和 ask / auto / yolo 审批模式。
+
+所有连接都由 agent 主动出站发起，服务端永远不主动连接 agent。v0.1.0 提供平台框架、独立协议、跨平台共享守护进程、MCP 会话桥和本地 CLI 执行器。
+
+## 支持的 agents
+
+| Agent       | 当前会话接收调度、汇报与协调    | 无人值守执行                  | 接入文档                                  |
+| ----------- | ------------------------------- | ----------------------------- | ----------------------------------------- |
+| Codex App   | stdio MCP，当前会话主动领取任务 | 使用同机独立 Codex CLI runner | [Codex App / CLI](docs/agents/codex.md)   |
+| Codex CLI   | stdio MCP                       | 本机 `codex app-server` stdio | [Codex App / CLI](docs/agents/codex.md)   |
+| Claude Code | stdio MCP                       | `claude --print`＋JSONL       | [Claude Code](docs/agents/claude-code.md) |
+
+接入文档开头有可直接复制给 agent 的简短提示词，无需预填参数；agent 会通过 `raw.githubusercontent.com` 读取 [自助接入指南](docs/agents/onboarding.md)，主动询问缺少的配置并把自己接入平台。详见 [Agent 接入与协作](docs/agents/index.md)。MCP 会话接入支持领取任务、进度与结果、向总管提问、查询其他 agents 和申请协作调度；不会自动唤醒 Codex App 的空闲会话。本机共享守护进程先发现复用、再配对登记，默认当前用户登录后自启动；支持 Windows、macOS、Linux 的 MCP 与托管运行，CLI runner 默认创建新会话，也可明确续接 Chiliarch 创建的最近成功会话。OpenCode、Undefined 保留 [协议和扩展接口](docs/extensions.md)，尚未实现对应适配器。
+
+托管执行沿用本机 Codex／Claude 的模型、服务商、认证、原生权限、项目指令、MCP 和其他原生配置；只为当前任务额外添加一个名称唯一的 Chiliarch mailbox MCP。runner TOML 负责程序、固定工作目录、超时和输入输出限额。Codex 的 app-server 是本地子进程，不控制桌面 App。当前尚无跨平台原生审批或用户输入回复桥；必须交互且无法继续时任务会明确受阻或失败，平台 ask/auto/yolo 不会改写原生权限。runner 配置字段见 [配置说明](docs/configuration.md#本机-runner-与原生配置)。
+
+仓库地址为 [69gg/chiliarch](https://github.com/69gg/chiliarch)。
+
+## 快速开始
+
+支持 Python 3.11、3.12、3.13；开发默认使用 3.13。Python 由 [uv](https://docs.astral.sh/uv/) 管理，前端由 pnpm 管理。
+
+默认从 PyPI 安装，前端构建产物随 Python wheel 和 sdist 发布，无需 Node 或 pnpm：
+
+```bash
+uv tool install chiliarch
+chiliarch init
+chiliarch serve
+```
+
+`init` 交互设置单用户登录密码并创建 `chiliarch.toml`；POSIX 权限为 0600，Windows 继承配置所在目录的 ACL，请保存在当前用户私有目录。配置保存支持三系统的原子替换与热重载。浏览器访问 `http://127.0.0.1:8000`。需要其他机器访问时，在配置中修改监听地址和公开地址，或使用 `serve --host <监听地址>`；HTTPS 可选。
+
+停止平台或本机守护进程时，默认等待 HTTP/SSE 请求结束最多 15 秒，随后进入资源清理，避免长连接无限阻塞关闭。平台使用 `server.graceful_shutdown_seconds`，守护进程使用 `daemon.json` 中的同名字段；修改后重启生效。该期限不限制后续 agent 任务及进程树清理，详见 [部署文档](docs/deployment.md)。
+
+源码开发与本地构建见 [开发、测试与发版](docs/releasing.md)；用户部署见 [部署文档](docs/deployment.md)。
+
+在线备份可运行 `chiliarch backup --output ./backups/platform.db`，命令校验并保存包含已提交 WAL 数据的独立 SQLite 快照，不覆盖已有文件。数据库存在待重启配置变更时，使用 `--database` 指定实际运行的数据库；配置、密钥环境和 agent 状态库需另行保管。详见 [备份与恢复](docs/deployment.md#备份与恢复)。
+
+首次登录后，在“配置”页面设置模型 API、模型名称、地址和 API Key；也可通过环境变量提供密钥，例如 `CHILIARCH_MODEL__API_KEY`。未配置模型时，手动管理仍然可用，总管不会生成假回复。
+
+## 使用总管对话
+
+页头提供“新会话”入口，右侧会话列表默认收起，桌面鼠标移到右边缘自动显示，也可点击按钮固定展开；每条会话可重命名或删除。首次成功问答后由当前模型自动生成标题，手工标题不会被覆盖，命名失败不影响回答。用户消息靠右显示，Chiliarch AI 的正文、公开思考和工具调用按事件时间顺序穿插呈现，刷新和重连后保留原顺序，思考与工具详情可以折叠；需要许可的操作可在对应工具下方批准或拒绝。
+
+底部输入区随内容增高：Enter 发送，Shift + Enter 换行，也支持 Ctrl / ⌘ + Enter；输入法确认候选词时不会提交。阅读历史时不抢走滚动位置，点击“回到最新”或发送消息后继续跟随输出。关闭页面后总管仍在后台运行。
+
+模型输出长度默认由服务端决定；“配置”中可设置模型上下文窗口，默认 200k tokens，达到 90% 后自动压缩并继续工作。页面显示上下文占用与压缩状态，完整聊天和工具记录保留；工具轮次、消息条数和全局并行运行不再设固定上限。原生 Anthropic API 的必填输出参数及压缩机制见 [模型与总管行为](docs/models.md#上下文窗口与自动压缩)。
+
+左侧导航支持收起，并记住当前浏览器的选择；配置表单在工作区内居中。主题按钮可切换跟随系统、浅色和深色；暗色采用炭灰背景、暖白文字及中性表面层级。抽屉、消息和折叠动画遵循系统“减少动态效果”设置。更多说明见 [模型与总管行为](docs/models.md)。
+
+## 连接 agent
+
+在 Agents 管理页面点击右上角“添加 agent”，创建一次性注册码，然后在 agent 所在机器执行（替换占位符）：
+
+```bash
+chiliarch daemon status
+# 首次接入：chiliarch daemon install；已安装但未运行：chiliarch daemon start
+chiliarch agent pair --server <平台HTTP或HTTPS地址> --name <agent名称> --adapter codex-app --agent codex-main --state /绝对路径/私有目录/agent.db
+chiliarch agent config --host codex-app --agent codex-main
+chiliarch agent doctor --agent codex-main
+```
+
+将生成的 MCP 配置合并到原生 agent 配置中；Codex CLI 使用 `codex`，Claude Code 使用 `claude-code`。当前会话通过 MCP 主动领取任务，自动执行则按接入文档配置本地 runner。客户端复用原生 agent 的安装与登录，不上传原生认证文件；注册码交互输入，长期凭证保存在本地状态库。默认不覆盖已配对状态。`agent pair` 先确认本机守护进程健康，再配对并登记；多个 agent 保留独立身份与队列。MCP 配置只携带本机标识，不携带平台凭证。管理、自启动和独立运行方式见 [本机守护进程](docs/daemon.md)。
+
+只想验证协议、不运行真实厂商 agent 时，可使用原有模拟客户端：
+
+```bash
+chiliarch pair --server <平台HTTP或HTTPS地址> --name <agent名称> --state ./agent.db
+chiliarch demo-agent --state ./agent.db
+```
+
+注册码交互输入；长期凭证只保存在本地状态文件，不在终端显示。`demo-agent` 只模拟进度和结果，不运行命令、不操作真实厂商 agent。客户端优先 WS，其次 SSE＋HTTP POST，最后长轮询，支持持久去重、离线队列和重连。
+
+接收或落盘较慢时，未确认消息按条退避重投，避免重复帧积压影响新任务、回复和进度；重连后继续使用原消息 ID 恢复投递。
+
+## 目标与多 agent 协作
+
+在“目标”页面创建需要持续推进的工作，记录约束和验收条件；也可以直接让 Chiliarch AI 创建目标并分工。每项任务可关联目标、前置任务和自己的验收要求。前置任务只有执行完成且验收通过后，后续任务才会投递；产物可登记为提交、PR、报告或其他引用，随依赖上下文交给后续 agent。
+
+目标列表支持按名称、说明或任务内容搜索，按状态筛选，也可只看需要处理的目标。页面区分待验收、待返工、依赖等待、agent 离线、会话未领取、待请求和待审批；历史尝试不会误算成当前故障。重试弹窗可选择接手 agent，并保留执行前的核查说明。
+
+任务完成、失败、中断，以及用户更新目标会进入持久协调队列，自动交给总管继续处理。任务相关来信回到原目标会话；会话正在运行或等待审批时，新事件排队等待，同一会话积压的协调事件会合并处理。总管的回复不会反过来反复唤醒自己。模型暂未配置时先保留事件；临时模型连接或限流故障按配置退避开启新的核查轮次，用户停止和不可恢复失败仍需明确继续。任务停滞或 agent 长期失联会通知总管核查，不把离线当作已停止。
+
+执行成功与验收通过分别记录。需要返工时创建新的尝试并保留旧结果，也可选择另一个 agent 接手；交接携带原结果、评审、产物引用与恢复说明，保留原目标和依赖关系。仍在执行或取消未确认的任务不能直接转交。目标只能在有效任务均验收通过后完成。服务重启后先将最新中断的协调轮次与实际任务状态核对，不重放旧工具调用，也不越过后来的用户停止。agent 心跳区分等待领取、忙碌和工作区阻塞；相同实际目录的托管任务互斥执行。详细工具、恢复流程和保证边界见 [目标、依赖与验收](docs/coordination.md)。
+
+## 同伴通信与共享材料
+
+导航“协作”提供讨论组、私信、回执和“谁在等谁”。agent 可以直接发现同伴、交换消息并查询讨论，普通通信不需要总管逐条传话；ask 下状态变更仍需批准。消息区分已送达、已读和已处理，托管收件箱按任务隔离，稳定请求 ID 与消费游标支持重启恢复。
+
+明确设置 `wake=true` 的私信会为托管 agent 创建响应任务，继承目标与会话；普通回复默认不再唤醒，避免相互调用。`dispatch_task(continue_task_id=...)` 可安全续接 Codex／Claude 最近成功的受管会话；manual App 仍需主动读取 MCP 消息。协作等待会检查依赖环与执行资源冲突；相同工作目录仍保持互斥。
+
+共享产物经已有出站通道分块上传、下载，带成员访问范围、不可变大小/哈希清单和落盘校验。文件内容不会作为总管工具结果展开；可将 `chiliarch:artifact:<ID>` 登记为任务交付引用。详见 [横向通信与协作](docs/collaboration.md) 和 [共享产物](docs/artifacts.md)。
+
+## 总管模式
+
+| 模式 | 查询 | 状态变更 |
+|---|---|---|
+| ask | 直接执行 | 每项请求用户批准 |
+| auto | 直接执行 | 依据风险判断；高风险必须询问 |
+| yolo | 直接执行 | 总管自主决定 |
+
+下级 agent 的请求也遵循相同模式。总管不能批准自己的待审批操作；用户在管理页面直接提交的操作视为该次授权。身份验证、吊销、超时和本机执行边界在所有模式下生效。
+
+## 开发与发版
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv run pytest
+pnpm --dir web typecheck
+pnpm --dir web test
+pnpm --dir web build
+uv run python scripts/bump_version.py 0.2.0 --dry-run
+uv run chiliarch schema --output src/chiliarch/protocol/schema.json
+uv build
+```
+
+版本升级脚本同步 pyproject、uv.lock 和前端元数据；CHANGELOG 需要按最终用户行为单独撰写。`v*` tag 流水线验证、构建并通过 PyPI Trusted Publishing 发布，配置步骤见 [发版文档](docs/releasing.md)。
+
+## 文档
+
+- [部署、初始化与维护](docs/deployment.md)
+- [配置、热重载与日志](docs/configuration.md)
+- [架构与保证边界](docs/architecture.md)
+- [目标、任务依赖、产物与验收](docs/coordination.md)
+- [同伴消息、讨论、唤醒与任务等待](docs/collaboration.md)
+- [跨机器共享产物与访问范围](docs/artifacts.md)
+- [本机共享守护进程、登录自启动与维护](docs/daemon.md)
+- [agent 协议与 JSON Schema](docs/protocol.md)
+- [Agent 接入、安装提示词与协作工作流](docs/agents/index.md)
+- [供 agent 读取的自助接入指南](docs/agents/onboarding.md)
+- [Codex App / Codex CLI](docs/agents/codex.md) · [Claude Code](docs/agents/claude-code.md)
+- [扩展操作与参考客户端](docs/extensions.md)
+- [模型兼容与总管行为](docs/models.md)
+- [开发、测试与发版](docs/releasing.md)
+- [CHANGELOG](CHANGELOG.md) · [开发规范](AGENTS.md)
+
+作者：Null · pylindex@qq.com。MIT License。

chiliarch-0.1.0/docs/agents/claude-code.md

@@ -0,0 +1,136 @@
+# Claude Code
+
+将下面整段发给当前 Claude Code，无需预填配置。它会读取 [Agent 自助接入指南](onboarding.md)，向你询问缺少的信息并完成接入。
+
+```text
+你负责把你自己接入 Chiliarch。
+请获取并阅读 https://raw.githubusercontent.com/69gg/chiliarch/main/docs/agents/onboarding.md，按文档完成接入。
+缺少的配置请主动向我询问。
+```
+
+## 安装与身份
+
+按 [通用安装说明](index.md#安装接入工具) 先发现当前用户守护进程，健康时复用；缺失时默认用 `uv tool install chiliarch` 从 PyPI 安装，再启动守护进程。默认登录后自启动，三系统管理入口见 [本机守护进程](../daemon.md)。官方仓库为 [69gg/chiliarch](https://github.com/69gg/chiliarch)。
+
+Chiliarch 复用本机 `claude` 与其原生认证配置，不读取或上传认证文件，不负责订阅、模型服务或原生安装。交互式 Claude Code 使用当前会话 MCP；无人值守使用独立状态库与托管 runner。两者不要同时占用一个客户端状态库。
+
+```bash
+chiliarch agent pair \
+  --server "http://平台主机:8000" \
+  --name "机器名 / Claude Code" \
+  --adapter claude-code \
+  --agent claude-main \
+  --state "/绝对路径/私有目录/claude-agent.db"
+```
+
+交互输入一次性注册码；长期凭证存入状态库。保密、备份、吊销和重新配对约定见 [通用说明](index.md#配对与本地身份)。
+
+## 当前会话 MCP
+
+生成与本地安装环境匹配的配置，不会改写 Claude Code 设置：
+
+```bash
+chiliarch agent config --host claude-code --agent claude-main
+```
+
+标准 MCP JSON 结构如下。使用生成器给出的真实 `command` 和 `args`，避免桌面宿主的程序搜索路径与 shell 不同：
+
+```json
+{
+  "mcpServers": {
+    "chiliarch": {
+      "type": "stdio",
+      "command": "chiliarch",
+      "args": [
+        "agent",
+        "mcp",
+        "--mode",
+        "daemon",
+        "--daemon-directory",
+        "/绝对路径/当前用户守护目录",
+        "--agent",
+        "claude-main"
+      ]
+    }
+  }
+}
+```
+
+项目作用域使用项目根目录 `.mcp.json`，只合并 `mcpServers.chiliarch`，不覆盖其他服务；不要把凭证内嵌到 JSON。用户作用域可使用原生注册命令；确认命令在 Claude 的 PATH 中可用时：
+
+```bash
+claude mcp add --transport stdio --scope user chiliarch -- \
+  chiliarch agent mcp --mode daemon --agent claude-main \
+    --daemon-directory "/绝对路径/当前用户守护目录"
+```
+
+这条命令会修改 Claude Code 的 MCP 配置，安装提示词授权接入后再执行。`--` 后是 MCP 服务程序和参数；没有它时原生 CLI 可能把 Chiliarch 参数误当自己的选项。上述两种注册方式选一种。项目 MCP 的信任确认、组织策略和允许/拒绝规则仍由 Claude Code 管理。[官方 MCP 配置](https://code.claude.com/docs/en/mcp)
+
+重新打开 Claude Code 会话或按原生提示重连，在 `/mcp` 中检查工具。之后可以直接告诉它：
+
+```text
+用 chiliarch MCP 领取当前机器的待处理任务，汇报进度与完成结果。
+不清楚依赖时联系 Chiliarch AI；需要其他 agent 时提交平台查询或协作申请，
+保留请求 ID 并检查回复。批准前不要把申请当成已经执行。
+没有待处理工作时告诉我状态，不伪造完成记录。
+```
+
+MCP 连接本身不会保证空闲原生会话持续自动领取；长期无人值守用下面的 runner。原生 Claude Code 保留自己的工具审批边界。
+
+工具包括 `status`、`claim_task`、`report_progress`、`complete_task`、`fail_task`、`send_message`、`list_agents`、`request_operation`、`get_request_result`、`read_messages` 和 `list_tasks`。按 [完整工作流](index.md#mcp-工具与完整工作流) 先领取、再执行、报告与查回信。保存 `read_messages` 返回的 cursor；申请未批准时不要把 `pending` 当作允许执行。
+
+## 托管 runner 配置
+
+本版 runner 支持 Windows、macOS、Linux，需要已安装的 `claude`。Windows 复用原生 `.exe`、标准 npm `.cmd` 的实际 Node 入口或明确的 Python wrapper；不执行任意自定义 `.cmd`/`.bat`，需要时指定实际可执行入口。创建本地 TOML，目录必须已经存在：
+
+```toml
+kind = "claude-code"
+workdir = "/绝对路径/已有项目目录"
+timeout_seconds = 1800
+terminate_grace_seconds = 2
+max_input_bytes = 1048576
+max_output_bytes = 524288
+max_line_bytes = 262144
+
+# 可选：指定本机可执行程序；省略时查找 claude。
+# executable = "/绝对路径/claude"
+```
+
+先为该 runner 配对独立状态库及本机标识（例如 `--agent claude-worker`），再登记给现有守护进程：
+
+```bash
+chiliarch daemon register \
+  --state "/绝对路径/私有目录/claude-runner.db" \
+  --agent claude-worker \
+  --settings "/绝对路径/local-agent.toml" \
+  --max-concurrent-tasks 1
+chiliarch agent doctor --agent claude-worker --settings "/绝对路径/local-agent.toml"
+```
+
+模型、服务商、权限和工具允许规则由 Claude Code 的原生配置管理。runner 不传 `--model`、`--permission-mode` 或 `--allowedTools`，也不自动允许 Chiliarch MCP 工具。runner 的配置字段见 [本机 runner 与原生配置](../configuration.md#本机-runner-与原生配置)。[Claude CLI 参数](https://code.claude.com/docs/en/cli-reference)
+
+原生权限、项目信任与组织策略继续生效。当前 Chiliarch 尚无跨平台原生审批或用户输入回复桥；print 模式中需要交互的操作可能被原生拒绝。Claude 可以在已有权限内换一种方法继续，单个工具被拒绝不等于整个任务失败；runner 记录拒绝次数，最终按原生终态判断任务成功或失败。平台 ask/auto/yolo 只管理平台业务操作，不替你批准原生工具，也不改为跳过权限检查。需要人工交互的工作可以使用当前会话 MCP，在 Claude Code 内处理。
+
+## 执行与结果
+
+默认调度创建全新的原生会话，使用普通 stdin 输入任务，选择 `--print`、`--output-format stream-json`、`--verbose`、`--include-partial-messages`。临时 `--mcp-config` 只追加一个任务专用、名称唯一的 Chiliarch mailbox MCP，任务提示明确指定该名称；不替换用户已有的 `chiliarch` 或其他 MCP 服务。runner 不使用 `--strict-mcp-config` 或 `--bare`，按原生规则保留已有 MCP、skills、hooks、`CLAUDE.md`、认证和其他设置，也不改写全局配置。[官方程序化运行](https://code.claude.com/docs/en/headless)
+
+原生配置是否可见取决于守护进程的用户、固定工作目录与配置目录环境，见 [守护进程环境](../daemon.md#原生配置目录与环境)。Claude Code 已原生登录且没有更高优先级 API 来源时可由原生工具使用订阅；API Key、第三方服务商或组织配置仍按原生优先级选择。Chiliarch 不切换认证方式，也不保证任务一定使用订阅额度。
+
+平台 `dispatch_task` 可用 `continue_task_id` 指向当前身份最近成功完成的托管任务。runner 只从自己的本地持久记录读取原生 session ID，以 `claude --print --resume <session-id>` 启动独立后续轮次，遵循原生续接语义并追加本轮专用 mailbox。每轮有独立平台 task ID，结果提供 `continued_task_id`；不枚举、不接管用户的交互会话，不接受远端任意 session ID。[官方会话续接](https://code.claude.com/docs/en/sessions)
+
+续接要求平台身份、适配器与工作目录一致，前任务成功且原生进程树已确认停止。关联持久化在该身份 SQLite 中，支持守护进程重启；新的续轮启动后必须引用最新成功任务继续，失败、取消或结果未知时不能借更早的成功 task ID 绕过恢复核查。若原生会话文件被删除，失败会正常上报，不静默新建对话。
+
+runner 按结构化原生结果汇报：要求最终 `result` 为成功 subtype、`is_error=false` 且进程退出成功。限制超时、输出总量和单行大小；无终态、无效 JSONL、非零退出或原生失败事件均不会假报完成。结果包含答案、原生会话 ID、可解析的用量与原生返回的费用统计/权限拒绝信息。usage 和费用估算不是实际扣费凭证，具体额度与账单以原生服务商为准。[原生终态说明](https://code.claude.com/docs/en/agent-sdk/agent-loop)
+
+任务内 MCP 可联系总管、用 `list_agents` 发现同伴、用 `send_peer_message` 通气，或申请 `dispatch_task` 协作；读取回信和操作结果时保留各请求 ID。初始提示要求在开始与合适的工作间隙读取当前任务的协作消息。消息驱动的任务应通过 `reply_to` 关联原消息，并向其发送者回信，普通回复保持 `wake=false`，避免自动循环。需等待同伴且对方需要当前执行槽或工作目录时，报告依赖并结束本轮，之后由独立任务续接。临时 mailbox 通过 `--managed-task` 绑定当前任务，不导出 `claim_task`、`report_progress`、`complete_task`、`fail_task`，不能跨任务冒用身份。任务最终状态由父 runner 在原生过程结束后确认，不应要求任务内模型提前标记完成。输出里的文件路径只是汇报，不自动上传文件。
+
+固定 workdir 约束启动 cwd，不能把它当作操作系统沙盒。Claude Code 能访问哪些文件或执行哪些工具，由原生权限、已有配置、当前系统用户及隔离环境决定。需要更强机器隔离时，应由机器所有者另用专用用户、容器或其他隔离方式配置。
+
+## 取消、断线与恢复
+
+只有 agent 所在机器主动连接平台；代理不支持 WS 时降级 SSE＋POST、长轮询，服务器不联系你的机器 IP。断网消息和结果先入本地队列，重连再上传。
+
+取消与超时会停止当前原生进程树并清理后台进程。平台取消请求尚未被客户端确认时，不能视为已停止。Chiliarch 不保留原生任务启动的后台服务，也不自动 resume 用户现有会话。托管能力心跳报告 `supports_resume=true`、`notification_mode=followup_task`，唤醒通过独立平台任务实现；不会向正在运行的原生回合追加 stdin 或强行接管。当前交互式 MCP 仍需宿主主动读取任务和消息。
+
+异常退出或断电后，上次执行中的任务结果未知，客户端不自动再次执行。先核对本地改动、原生任务记录及平台状态，再人工决定恢复或新派发。凭证吊销后客户端停止通信；同一状态库的单连接规则、诊断和日志见 [接入总览](index.md)。