taifeng 0.0.1__tar.gz

taifeng-0.0.1/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+# 发布到 PyPI —— 基于 GitHub Trusted Publishing（OIDC，无需在仓库存 token）
+# 触发：推送形如 v* 的 tag（如 v0.0.2）即自动构建并发布。
+# 一次性前置：在 https://pypi.org/manage/account/publishing/ 把本仓库 + 本文件名
+#   (publish.yml) + environment (pypi) 登记为 trusted publisher。
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    # environment 名需与 PyPI trusted publisher 配置中的一致
+    environment: pypi
+    permissions:
+      # OIDC 令牌签发权限 —— Trusted Publishing 必需，缺它会鉴权失败
+      id-token: write
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+
+      - name: 安装 uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: 构建 wheel 与 sdist
+        run: uv build
+
+      - name: 校验 tag 版本与 pyproject 版本一致
+        # 防止打错 tag：tag 去掉前缀 v 后必须等于 pyproject.toml 的 version
+        run: |
+          tag_version="${GITHUB_REF_NAME#v}"
+          proj_version="$(uv version --short)"
+          if [ "$tag_version" != "$proj_version" ]; then
+            echo "::error::tag ($tag_version) 与 pyproject version ($proj_version) 不一致"
+            exit 1
+          fi
+
+      - name: 发布到 PyPI（Trusted Publishing）
+        run: uv publish --trusted-publishing always

taifeng-0.0.1/.gitignore

@@ -0,0 +1,160 @@
+.history/
+.codex/
+.claude/
+.taifeng-*
+.ruff_cache/
+
+.playwright-mcp/*
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# Taifeng runtime artifacts
+.taifeng/
+threads/
+*.jsonl
+*.db
+*.db-shm
+*.db-wal
+
+# Editor / OS
+.vscode/
+.idea/
+.DS_Store
+

taifeng-0.0.1/AGENTS.md

@@ -0,0 +1,110 @@
+# AGENTS.md —— Taifeng 工程协作约定
+
+> 本文件供 AI agent (Claude Code / codex / claw) 在本仓库工作时遵守。
+
+## 项目身份
+
+**Taifeng (泰逢)**：通用 LLM Agent 微内核 / OS 调度器。
+独立 infra 包，不绑定任何业务系统。第一个生产用户是 宿主业务，但**绝不引入 宿主业务 概念**。
+
+## 工作目录
+
+- `src/taifeng/` —— 核心实现（6 个子包：skill / tool / conversation / context / llm / loop + telemetry）
+- `tests/` —— pytest（asyncio_mode=auto）
+- `examples/` —— 端到端示例（mock 客户端，无需 API key）
+- `docs/` —— 架构 + ADR + 调研
+- `docs/architecture/capabilities/` —— 能力契约（契约先行：数据结构 / 协议 / 事件 / 约束）
+
+## 多 Session 并发协作（一 session 一 worktree）
+
+> 多个 AI session 并发在本仓库工作时，**绝不共用主工作树**。
+> 教训（真实事故）：主工作树只有**一个共享的 HEAD / index / 工作目录**，谁 `git checkout` 切分支，就把 HEAD 从别人脚下抽走 —— 导致 commit 落错分支、别人的未提交改动被串走、被迫做 git 手术。**开分支 ≠ 隔离；独立的工作目录才隔离。** 因此"每个 session 各开分支但共用主树"恰恰是最乱的组合。
+
+**三条硬规则：**
+
+1. **主树只做集成**：任何 session **都不**在主树（`<repo-root>`）里做开发或 `git checkout` 切分支。主树仅用于最终 merge 或当干净参照。
+2. **一 session = 一 worktree = 一分支**：session 启动即 `git worktree add .claude/worktrees/<task> -b feat/<task> <integration-point>`，全程钉死在自己的 worktree 里；**从不 `cd` 回主树、从不动别人的分支、从不切主树 HEAD**。
+3. **任务范围作所有权单元**：一个 session 认领一个明确的任务范围；尽量按目录切分工（如 A 只碰 `loop/`、B 只碰 `context/`），减少重叠。
+
+**降冲突：**
+
+- `loop/event.py`（`MsgKind` / `Msg` Union 全局注册表）这类"全局枚举/注册表"是冲突高发区 —— 让单一 session 统一增改，或频繁从集成分支 rebase 早暴露冲突。
+- 集成时**一次只合一条分支**，合完立即跑全量 `PYTHONPATH=src uv run pytest tests/` 再合下一条；不要同时合多条。
+
+**操作前自检 + 收尾：**
+
+- 动手提交前先 `git rev-parse --abbrev-ref HEAD` 确认在自己的 worktree 分支上。
+- 合并完成后 `git worktree remove <path>` + `git branch -d <分支>`（`-d` 会校验已完全合并才删，安全）。
+- 注：本仓库是 **git submodule**，worktree 建在 submodule 工作树下（`.claude/worktrees/`），不要建到父仓库去。
+
+## 五条审 PR 红线（任何变更必须遵守）
+
+1. **业务零侵入** —— 禁止 `tenant_id` / 业务术语 / 宿主业务 模块 import
+2. **Cache 友好** —— 压缩必须返回 `cache_invalidated: bool` + `anchor_preserved_until: int`
+3. **可观测** —— turn / tool / skill / compaction / cache_break 都必须有 EventMsg
+4. **可取消** —— 长时操作接收 `CancellationToken`；不允许阻塞主 actor
+5. **可 resume** —— 默认实现是 JSONL 追加写；其他 store 用 `MessageStore` 协议
+
+## 实现约束
+
+- Python 3.12+，类型注解全部 `from __future__ import annotations`
+- 异步用 `anyio`（必要时回退 `asyncio`），不用同步阻塞调用
+- 数据类用 `@dataclass(frozen=True)` 或 `pydantic.BaseModel`
+- 文件 ≤ 800 行硬红线；函数 ≤ 80 行；圈复杂度 ≤ 10
+- 注释中文（覆盖默认 no-comments 规则）；module/class/function 必须有 docstring
+- 配置走依赖注入；禁止 `os.getenv` 在 src/ 内
+
+## 测试约束
+
+- 新模块必须有 `tests/test_<module>.py`
+- LLM 调用走 `MockClient` —— 不能在 CI 里调真实 API
+- 文件 IO 走 `tmp_path` fixture
+- 边界必测：cancel、空输入、超长 body、环检测、深度上限
+
+## 命令速查
+
+```bash
+# 安装
+uv venv && uv pip install -e ".[dev,litellm]"
+
+# 测试（全套）
+PYTHONPATH=src uv run pytest tests/ -v
+
+# 示例（basic/ 与各 pattern demo 走 MockClient，无需 API key；real_llm/ 需真实 key）
+PYTHONPATH=src uv run python examples/basic/minimal_chat.py
+PYTHONPATH=src uv run python examples/basic/composite_skill.py
+PYTHONPATH=src uv run python examples/orchestration/demo.py   # 声明式编排
+PYTHONPATH=src uv run python examples/mcp_basic/demo.py       # taifeng 作为 MCP server
+# 完整清单见 examples/ 各子目录（instructions_basic / skill_with_script / research_assistant /
+#   travel_planner / code_review / mcp_hitl / permission / persistence / web_ui ...）
+
+# CLI
+PYTHONPATH=src uv run python -m taifeng skill list /path/to/skills
+PYTHONPATH=src uv run python -m taifeng skill validate /path/to/skills
+```
+
+## 能力契约工作流（contract-first）
+
+1. 定契约：在 `docs/architecture/capabilities/<capability>.md` 写清数据结构 / 协议 / 事件 / 约束
+2. 实现：小步切片，每步完成立即 commit；红测试不可跳过
+3. 同步：更新对应 `docs/architecture/<module>.md` 活文档
+
+## 文档义务
+
+`docs/README.md` 是文档索引 + 分类约定（权威）。两类文档处理方式不同，别混用：
+
+- `docs/architecture/` = 当前架构**活文档**（含 `capabilities/` 契约层）→ 改了 `src/` 设计 / 数据流就**更新**对应篇（§编号对应：skill→skill-system、loop+tool→agent-loop、conversation、context→context-compression、llm→llm-client、切分→overview）。永远代表现状，**不归档、不堆废弃史**。
+- `docs/decisions/` = ADR → **只增不改**，推翻写新 ADR 标 `Supersedes #NNNN`。
+
+**判据**：写"现状"进 architecture（模块篇或 `capabilities/` 契约），写"决策 / 为什么"进 ADR。
+**硬约束**：实现完成但 architecture 未同步 → 不得 archive，PR 不合并。
+
+## 参照实现
+
+代码参照三个开源项目（位于本机 `<opensource>/`）：
+
+- **codex** (Rust) —— 范式权威。`codex-rs/core/src/compact.rs` / `client.rs` 是 cache-aware + handoff 的源头
+- **claw-code** (Rust) —— Claude Code 开源移植。`crates/runtime/src/compact.rs` 含 tool 配对边界保护
+- **openclaw** (TS) —— `src/agents/*` 提供 actor + session 模式
+
+移植到 Python 时**只学范式，不抄代码**（语言习惯不同）。

taifeng-0.0.1/CLAUDE.md

@@ -0,0 +1,192 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+> 配套文件：`AGENTS.md` 是给所有 AI agent 看的工程协作约定；本文件聚焦 Claude Code 在本仓库执行任务时需要的快速上下文。两者冲突时以 `AGENTS.md` 为准（它是更早的工程契约）。
+
+## 项目身份
+
+**Taifeng (泰逢)** —— 通用 LLM Agent **微内核 / OS 调度器**（不是织造工具，不是业务框架）。Python 3.12+，对标 codex (Rust) / Claude Code (TS) / claw-code (Rust) 的 CLI agent 范式，为 Python 服务端提供可嵌入的 agent 引擎。
+
+**关键定位**：
+- 是独立 infra 包，**与业务完全解耦**。`src/` 内**禁止出现任何业务概念**（无 tenant / 无领域名词 / 无 LLM provider lock-in）。
+- 不与 LangGraph / AutoGen / Letta 竞争（不同范式：codex 风格 vs 图/Actor/记忆）。
+- 范式核心：**skill 是 markdown**（不是 function tool）、**LLM 是调度器**（不是被调度对象）、**压缩 cache-aware**、**Actor 风格 Submission/EventMsg 双总线**。
+
+## 常用命令
+
+```bash
+# 安装（uv 是必须，不用 pip）
+uv venv && uv pip install -e ".[dev,litellm]"
+
+# 跑全部测试（必须带 PYTHONPATH=src，因为是 src-layout）
+PYTHONPATH=src uv run pytest tests/ -v
+
+# 跑单个测试文件
+PYTHONPATH=src uv run pytest tests/test_engine_e2e.py -v
+
+# 跑单个测试
+PYTHONPATH=src uv run pytest tests/test_dispatch.py::test_circular_reference_detection -v
+
+# 端到端示例（examples/basic/ 与各 pattern demo 均走 MockClient，无需 API key）
+PYTHONPATH=src uv run python examples/basic/minimal_chat.py
+PYTHONPATH=src uv run python examples/basic/composite_skill.py
+PYTHONPATH=src uv run python examples/basic/instructions_basic.py   # 指令分层注入 + 热更
+PYTHONPATH=src uv run python examples/basic/skill_with_script.py    # SKILL.md scripts 运行时
+PYTHONPATH=src uv run python examples/orchestration/demo.py         # 声明式编排（parallel/serial/when）
+PYTHONPATH=src uv run python examples/mcp_basic/demo.py             # taifeng 作为 MCP server
+# 其余 pattern demo：research_assistant / travel_planner / code_review / product_review /
+#   numeric_loop / mcp_hitl / selective_approval / subagent_isolation / observability /
+#   permission / persistence / web_ui —— 见 examples/<name>/demo.py（或 server.py）
+PYTHONPATH=src uv run python examples/real_llm/e2e.py               # 需要真实 LLM API key（real_llm/ 下均是）
+
+# CLI（用于排查 SKILL.md 目录）
+PYTHONPATH=src uv run python -m taifeng skill list <skills_dir>
+PYTHONPATH=src uv run python -m taifeng skill show <skills_dir> <skill_id>
+PYTHONPATH=src uv run python -m taifeng skill validate <skills_dir>
+PYTHONPATH=src uv run python -m taifeng engine demo <skills_dir> <entry_id> -m "..."
+
+# Lint / 类型检查（pyproject.toml 已配 ruff + mypy strict）
+uv run ruff check src/ tests/
+uv run mypy src/
+```
+
+`pytest.ini_options.asyncio_mode = "auto"` —— 所有 async 测试函数无需 `@pytest.mark.asyncio` 装饰。
+
+## 完成定义（DoD）
+
+标记 task 完成、回报"已完成"、或提交 commit 前必须做到：
+1. **跑通验证命令**：相关 `pytest tests/test_<x>.py` 全绿，或对应 example 端到端无异常。
+2. **复述实际命令 + 关键输出**：不是"应该 OK"，而是贴命令与输出。
+3. 红测试**禁止**以 "pre-existing" 为借口跳过。先排查是否与本次改动相关。
+
+## 多 Session 并发协作
+
+多个 session 并发在本仓库工作时**绝不共用主工作树**——主树只有一个共享 HEAD，谁切分支就把 HEAD 从别人脚下抽走，会导致 commit 落错分支 / 别人未提交改动被串走（**开分支 ≠ 隔离，独立工作目录才隔离**）。规则：
+
+1. **主树只做集成**，不在主树开发或 `git checkout` 切分支；
+2. **一 session 一 worktree 一分支**：`git worktree add .claude/worktrees/<task> -b feat/<task> <integration-point>`，全程钉死其中，不 `cd` 回主树、不动别人分支；
+3. **一个 session 认领一个明确的任务范围**，按目录切分工降冲突（`loop/event.py` 等全局注册表是冲突高发区）；
+4. 集成**一次合一条**分支 + 跑全量 `PYTHONPATH=src uv run pytest tests/`；收尾 `git worktree remove` + `git branch -d`。
+
+> 完整约定（含真实事故教训、submodule 注意点）见 `AGENTS.md` 「多 Session 并发协作」节。
+
+## 五条审 PR 红线（任何变更必须遵守）
+
+| # | 红线 | 落实方式 |
+| --- | --- | --- |
+| **R1 业务零侵入** | `src/` 内禁止业务概念：`tenant_id`、`audience`、领域名词（无论中英文）、业务子模块路径 | 业务侧通过 `AgentPolicy` 钩子注入策略 |
+| **R2 Cache 友好** | 压缩动作必须返回 `CompressionResult { cache_invalidated: bool, anchor_preserved_until: int }` | mid-turn 只改 tail；pre-turn 才允许动 head |
+| **R3 可观测** | 关键路径必须打 `EventMsg`：`turn_started` / `tool_dispatched` / `compaction_attempted` / `cache_break_detected` / `provider_retry` | 通过 `TelemetrySink` 协议，不绑定后端 |
+| **R4 可取消** | 长时操作必须接收 `CancellationToken`；子 agent 通过 `cancel.child()` 派生 | 不允许阻塞主 actor |
+| **R5 可 resume** | 默认 store 是 JSONL 追加写；业务侧落 DB 自行实现 `MessageStore` 协议 | `MessageStore` 在 `conversation/store.py` |
+
+## 实现约束（src/ 内强制）
+
+- **Python 3.12+**，所有模块顶部 `from __future__ import annotations`
+- **异步**用 `anyio`（必要时回退 `asyncio`），不写同步阻塞 IO
+- **数据类**用 `@dataclass(frozen=True)` 或 `pydantic.BaseModel`
+- **配置**通过依赖注入；**`src/` 内禁止 `os.getenv`**（业务侧读环境变量后传入构造函数）
+- **文件 ≤ 800 行**硬红线，警戒线 500；**函数 ≤ 80 行**；圈复杂度 ≤ 10
+- **中文注释**（覆盖默认 "no comments" 规则）：所有 module / class / function 必须有 docstring；关键逻辑块行内中文注释
+- **错误**：分类到既有 `LLMError` / `DispatchVerdict` 子类，禁止 silent fallback（`except: pass`、`data.get('x', 默认值)`）
+
+## 测试约束
+
+- 新模块必须有对应 `tests/test_<module>.py`
+- LLM 调用走 `MockClient` —— **CI 内禁止调用真实 API**（`tests/` 全部用 mock；真实 LLM 验证只在 `examples/real_llm_*.py`）
+- 文件 IO 走 `tmp_path` fixture，不写仓库内固定路径
+- **边界必测**：cancel / 空输入 / 超长 body / 环检测 / 深度上限 / 并发
+
+## 架构总览
+
+详见 `docs/architecture/overview.md`。一张图速记：
+
+```
+src/taifeng/
+├── skill/        # §1.1 SkillDefinition (atomic/composite) / loader / registry / dispatch / 环检测 / FileWatcher
+├── tool/         # §1.2 tool 部分：ToolSpec (parallel_safe) / Runtime（RwLock 并行调度）/ builtins
+├── conversation/ # §1.3 ResponseItem / MessageStore 协议 / JsonlMessageStore + SQLite 旁路索引
+├── context/      # §1.4 ContextBudget / CompressionStrategy 协议 / Handoff + Sliding 策略 / cache_stats
+├── llm/          # §1.5 ModelClient 协议 / ResponseEvent / retry / providers (litellm / openai_compat / mock)
+├── loop/         # §1.2 主循环：Submission/Op + EventMsg + Engine（主 actor）+ TurnRunner + Pool + Cancellation
+├── hooks/        # PreToolUse / PostToolUse / PreCompact / PreTurn（claw-code 范式）
+├── permission/   # HITL 审批：PermissionPolicy + Rule + Prompter（CLI / Callback）
+├── mcp/          # MCP stdio client（连外部 MCP server 自动注册 tools）
+└── telemetry/    # ConsoleSink + JsonlSink（其他后端业务侧自接）
+```
+
+按 ADR 0006 **统一为 Skill 抽象** —— 没有独立的 `agent/` 包，skill-to-skill 派发归 `skill/dispatch.py`，composite skill 替代 agent 概念。
+
+### 一次 turn 的数据流（速记）
+
+```
+Submission(UserMessage) → AgentEngine 入队 → TurnRunner.run_turn
+  ├─ pre-sampling 压缩检查（动 head 允许）
+  ├─ build_prompt（entry_skill body + child skills 列表[只 id+description, 不含 body]）
+  ├─ ModelClientSession.stream → ResponseEvent 流
+  │    ├─ TextDelta → EventMsg.AssistantText
+  │    ├─ ToolCallDone(read_skill)  → 取子 skill body 回流
+  │    ├─ ToolCallDone(call_skill)  → DispatchPolicy.check（深度/环/白名单）→ 派子 TurnRunner
+  │    ├─ ToolCallDone(其他)        → ToolCallRuntime.dispatch（parallel_safe ? 读锁 : 写锁）
+  │    └─ Completed → break
+  ├─ mid-turn 压缩检查（只动 tail，保 cache anchor）
+  └─ MessageStore.append → JSONL flush
+→ AgentEngine emit EventMsg.TurnComplete
+```
+
+## 关键抽象（找代码用）
+
+| 你想做 / 改 | 看这里 |
+| --- | --- |
+| SKILL.md 字段、frontmatter 校验 | `src/taifeng/skill/definition.py` + `loader.py` |
+| call_skill 派发 / 深度环检测 | `src/taifeng/skill/dispatch.py` |
+| 内置工具 (read_skill / call_skill / file_read / file_write / shell_exec) | `src/taifeng/tool/builtins/` |
+| 压缩策略 (handoff / sliding) | `src/taifeng/context/strategies/` |
+| 多 provider 适配 | `src/taifeng/llm/providers/` |
+| 主循环 / Engine / Pool | `src/taifeng/loop/engine.py` + `turn.py` + `pool.py` |
+| 业务可配置参数全清单 | `docs/configurable-knobs.md`（构造时参数 + 运行时 Op + Engine 公开属性）|
+| 公共 API 一览 | `src/taifeng/__init__.py` 的 `__all__` |
+
+## 能力契约工作流（contract-first）
+
+每个能力的**稳定契约**（数据结构 / 协议 / 事件 / 约束）落在 `docs/architecture/capabilities/<capability>.md`，索引见 [`docs/architecture/capabilities/README.md`](docs/architecture/capabilities/README.md)。
+
+```
+docs/architecture/capabilities/<capability>.md   # 能力契约（数据契约 + 行为契约）
+docs/architecture/<module>.md                     # 模块叙述活文档（如何协作）
+docs/decisions/NNNN-*.md                          # ADR（为什么这么定）
+```
+
+工作流：先定/更新能力契约 → 小步实现（每步完成即 commit，≤ 3h）→ 同步对应 `architecture/<module>.md` 活文档。涉及压缩 / cache / dispatch 的改动 **必须显式声明对 R1–R5 的影响**。
+
+## 文档体系与义务
+
+> 文档索引与分类约定的**权威**在 `docs/README.md`。下表是速查——四类文档**寿命不同、处理方式不同，禁止混用**：
+
+| 目录 | 是什么 | 设计 / 逻辑变更后怎么处理 |
+| --- | --- | --- |
+| `docs/architecture/` | **当前生效的架构设计**（活文档，含 `capabilities/` 契约层） | **更新**对应模块篇 / 契约，永远代表现状；**不归档、不堆废弃史** |
+| `docs/decisions/` | ADR 决策记录（为什么这么定） | **只增不改**；要推翻写新 ADR 标 `Supersedes #NNNN` |
+
+**判据**：这条信息是"系统现在的样子" → 改 architecture（模块篇或 `capabilities/` 契约）；是"某次决策的经过 / 为什么" → 记 ADR，**不往 architecture 堆废弃史**（例：砍掉某 Op 的理由进 ADR，architecture 只写"现在有哪几种 Op"）。
+
+改了 `src/` 模块的设计 / 数据流，必须同步**对应** architecture 篇（§编号一一对应：`skill/`→skill-system、`loop/`+`tool/`→agent-loop、`conversation/`→conversation、`context/`→context-compression、`llm/`→llm-client、模块切分→overview）。
+
+**硬约束**：实现完成但 architecture（模块篇 / 契约）未同步 → PR 不合并（同 `docs/README.md` 维护红线）。
+
+## 参照实现
+
+设计范式参照 `<opensource>/` 下三个开源项目（**只学范式，不抄代码**，语言习惯不同）：
+
+- **codex** (Rust) —— `codex-rs/core/src/{compact.rs, client.rs, session/*}`：cache-aware + handoff 源头
+- **claw-code** (Rust) —— `crates/{runtime, api}/src/*`：tool 配对边界保护、hooks、permission
+- **openclaw** (TS) —— `src/agents/* + src/context-engine/*`：actor + session 模式
+
+不抄业务概念。所有移植后的 Python 文件必须有「参照 X，差异 Y」的注释或 ADR 说明。
+
+## 语言要求
+
+- 文档、注释、commit message、PR 描述：**中文**
+- 变量 / 函数 / 类名：**英文**（遵循 PEP 8 与社区惯例）
+- 与用户沟通：中英文均可，看用户偏好