openmodus 0.0.3__tar.gz → 0.0.4__tar.gz

openmodus-0.0.4/ARCHITECTURE.md

@@ -0,0 +1,123 @@
+# 架构设计
+
+Modus 将三个生命周期分开管理：**接入资产让工作流可用，初始化分析提供可丢弃的证据，经过评审的 Markdown 保存长期知识**。日常检索读取当前源码与知识正文，不重建或重开初始化数据。模块围绕各自拥有的数据、失败语义与变更边界划分。
+
+<!--
+阅读入口按职责排列；新增入口时核对真实的模块所有者。
+-->
+
+## 从这里开始阅读
+
+1. [CLI 组合入口](src/modus/cli.py)：五个公开命令与供技能调用的内部适配器。
+2. [项目安装](src/modus/commands/init_project.py)：预检、计划写入、回滚与清单发布。
+3. [分析 API](src/modus/machine/api.py)：构建、验证后打开、证据筛选与创作上下文。
+4. [上下文解析](src/modus/orchestrator/context_resolver.py)：一个请求、一个共享预算、一份当前证据。
+5. [知识更新](src/modus/knowledge_update.py)与[写入会话](src/modus/knowledge_write_session.py)：所有权、读取时哈希、并发冲突与原子发布。
+
+<!--
+依赖方向与写入所有权同时约束扩展，不能仅凭导入无环判断分层。
+-->
+
+## 依赖与所有权
+
+```mermaid
+flowchart TB
+    CLI[CLI 组合入口] --> Terminal[终端适配器]
+    Terminal --> Commands[应用命令]
+    Terminal --> Machine[初始化分析]
+    Terminal --> Display[中文帮助与诊断]
+    Commands --> Install[模板与平台适配]
+    Commands --> Orchestration[上下文与影响编排]
+    Orchestration --> Retrieval[当前 Markdown 与源码检索]
+    Commands --> Verify[知识完整性核验]
+    Commands --> Writes[知识写入会话]
+    Install --> Manifest[所有权清单]
+    Machine --> Cache[临时证据包]
+    Writes --> Knowledge[长期 Markdown 知识]
+```
+
+| 边界 | 所有者 | 扩展规则 |
+| --- | --- | --- |
+| 命令树与全局参数 | `cli.py` | 显式注册公开入口，不承载工作流实现 |
+| 参数、交互、流与退出码 | `cli_commands/` | 按工作流拆分适配器，不修改 Click 全局状态 |
+| 中文帮助与解析错误 | `cli_commands/presentation.py` | 从已注册参数生成帮助，仅适配框架固定句式 |
+| 分析进度与恢复提示 | `cli_commands/analysis_display.py` | 转换展示副本，不改证据、摘要或 JSON 契约 |
+| 协议值的展示名称 | `display_labels.py` | 终端与 Markdown 复用；未知值保留原标识 |
+| 安装与维护事务 | `commands/` | 返回结构化结果，展示由 `*_report.py` 负责 |
+| 平台中立的工作流分发 | `scaffold/` | 验证静态模板并记录资产所有权 |
+| 宿主差异 | `platforms/`、`hooks/` | 声明布局，复用合并与卸载契约；`platforms/display.py` 统一平台显示名与交互顺序 |
+| 初始化分析 | `machine/` | 单向语义阶段，显式覆盖缺口 |
+| 任务编排 | `orchestrator/` | 组合证据与策略，不拥有搜索算法或写入 |
+| 检索 | `retrieval/` | 共享截止时间与输出预算，明确返回部分结果 |
+| 完整性 | `knowledge_verification/` | 报告客观缺陷，不给正文质量打分 |
+| 长期写入 | `knowledge_write_session.py` | 路径约束、所有权、哈希条件写入、锁与原子替换 |
+
+<!--
+机器层的确定性不等于业务结论的完整性，二者各有验收责任。
+-->
+
+## 分析证据是创作输入
+
+```text
+N1 源码基线 → N2 程序事实 → N3 关系解析 → N4 能力模型 → N5 创作投影 → N6 证据包
+```
+
+后续阶段消费前序契约。投影与打包不能重新读取源码来补造缺失观察。存储与资源策略不依赖任何语义阶段。[架构测试](tests/machine/test_architecture.py)检查这些方向，包括函数内的延迟导入。
+
+可选解析器或编译器缺失，只产生对应范围的覆盖回执。契约、完整性、输入漂移或必需工具失败会中止本轮。完整证据包经过核验后才原子发布；失败不能替换已有完整包，也不能把旧包当作当前证据。消费者必须提供本轮身份，并使用经过认证且有预算限制的查询。
+
+[分析层指南](src/modus/machine/README.md)说明扩展注册、进度、摘要与错误码。编译器观察属于 N2；语言适配器无权决定最终业务边界。
+
+同一阶段内部继续按责任分解：
+
+| 职责 | 组合入口 | 支撑模块 |
+| --- | --- | --- |
+| 原子发布 | [产物 I/O](src/modus/artifacts_io.py) | [原子写入](src/modus/atomic_writes.py)负责描述符绑定与替换；锁与 YAML 加载留在产物 I/O |
+| 文件内解析 | [原生解析器](src/modus/machine/facts/native_parser.py) | [语法契约](src/modus/machine/facts/native_syntax.py)定义语法类别与可移植结果；[访问器](src/modus/machine/facts/native_visitor.py)负责单文件遍历，入口负责解析器选择与生命周期 |
+| 框架观察 | [前端入口](src/modus/machine/facts/frontend.py) | [上下文](src/modus/machine/facts/frontend_context.py)、[状态](src/modus/machine/facts/frontend_state.py)与[服务路由](src/modus/machine/facts/frontend_server.py)共享源码锚点，不执行应用 |
+| 拓扑 | [拓扑组装](src/modus/machine/resolution/topology.py) | [规则](src/modus/machine/resolution/topology_rules.py)、[记录](src/modus/machine/resolution/topology_records.py)与[资源](src/modus/machine/resolution/topology_resources.py)分开处理分类和发布 |
+| 目录投影 | [证据目录](src/modus/machine/store/bundle_catalogs.py) | [范围目录](src/modus/machine/store/scope_catalog.py)拥有范围记录，[构建原语](src/modus/machine/store/catalog_building.py)共享规范化操作 |
+| 工作区地图 | [工作区服务](src/modus/workspace.py) | [地图渲染](src/modus/workspace_maps.py)只消费观察，不读写成员仓库 |
+
+移动解析实现时必须同步实现指纹。观察结果的缓存身份要随访问器或语法契约变化而失效，仅以源码内容作为缓存键不够。
+
+<!--
+人工正文的所有权与分析缓存不同，重建证据不得覆盖人工知识。
+-->
+
+## 长期知识有独立的生命周期
+
+| 接入项目中的位置 | 生命周期与权限 |
+| --- | --- |
+| `.modus/` 与平台接入文件 | 框架受管资产，由清单保护用户修改 |
+| `modus/.cache/` | 可丢弃的分析与临时创作状态 |
+| `modus/knowledge/` | 经评审、随项目版本管理的 Markdown |
+| 知识中的 `business/` 与 `constraint/` | 默认由人工维护，自动化修改需要明确授权 |
+
+[创作契约](docs/authoring-contract.md)区分证据闭环、面向读者的正文与发布。机器建议指导调查，当前源码、测试、配置与明确材料确立事实。结构核验 `clean` 不等于业务事实正确或正文清晰。
+
+写入使用准备修改时观察到的哈希。并发修改形成冲突，不被覆盖。迁移先建立新主定义、修复链接，再删除旧生成文件。知识更新批次按文件报告独立结果，不承诺全批回滚；安装事务则对计划目标创建快照，失败时尝试精确回滚，并明确报告恢复不完整。
+
+<!--
+日常读取使用当前项目内容，初始化数据不是长期检索索引。
+-->
+
+## 检索始终面向当前项目
+
+[编排层](src/modus/orchestrator/README.md)选择范围并组装协议；[检索管线](src/modus/retrieval/README.md)负责渐进发现 Markdown、词法与结构排序、源码采集和交付。整个请求共用一个预算，缺失证据、不安全文件与截断都可见。运行时不能用初始化缓存替代当前源码。
+
+仅在执行分析命令时导入分析依赖。帮助、状态、安装和普通源码/Markdown 检索不提前加载解析器、图依赖或分析管线。
+
+<!--
+展示语言可本地化，稳定命令、字段和错误码仍保持机器兼容。
+-->
+
+## 中文体验与公开契约
+
+面向用户的帮助、交互、诊断、生成知识和维护文档默认使用简体中文。命令名、参数、路径、Python 标识、JSON 字段、状态值与稳定错误码保持协议原样。用户明确指定其他正文语言时，创作工作流遵从该要求。
+
+中文化在拥有文本的边界完成：命令目录维护语义说明，报告模块维护结果展示，终端层适配框架默认提示，模板维护创作约定。错误信息说明问题与恢复动作，第三方工具的原始诊断可作为细节保留。不得通过全局猴子补丁、整段输出替换或改写传输字段实现本地化。
+
+增加宿主时扩展经过验证的平台注册表；增加语言时同步声明、版本化实现与支持/降级夹具；增加检索信号时修改其所属阶段。不要仅为缩短文件创建抽象，只有所有者、生命周期或失败策略不同才拆分。
+
+[贡献指南](CONTRIBUTING.md)说明命名、注释与验证要求。[发布工具](scripts/README.md)检查源码包和 wheel，并脱离源码仓库运行已安装产物。

openmodus-0.0.4/CONTRIBUTING.md

@@ -0,0 +1,68 @@
+<!--
+开发工具版本与锁文件一起维护，指南不维护第二套依赖约束。
+评审关注可观察行为与所有权，不用格式改动代替设计说明。
+新增边界应说明输入、失败结果与兼容性。
+语言约定只改变展示，机器字段和稳定路径保持原义。
+本地验证结果需注明环境，未运行的平台不作通过承诺。
+-->
+
+# 参与贡献
+
+先阅读[架构设计](ARCHITECTURE.md)，再进入待修改模块的 README。一项变更应围绕一个可观察行为或一个所有权边界展开。提交说明写清问题、修改后的行为与相关验证，便于未参与讨论的维护者评审。
+
+## 本地开发
+
+使用 Python 3.11–3.14，在 Git 工作区按已提交的 uv 锁文件安装：
+
+```bash
+uv sync --locked --extra test
+uv run --locked --extra test pytest -q
+uv run --locked --extra test ruff check src tests scripts
+uv run --locked --extra test ruff format --check src tests scripts
+uv run --locked --extra test mypy
+git diff --check
+```
+
+发布前执行 `./scripts/wheel-smoke.sh`：重新构建 wheel 与源码包、检查内容，并运行独立的 wheel 验收。该脚本不发布安装包。源码包附带测试与发布脚本，下游维护者可复现检查。
+
+CI 覆盖 Linux 的 Python 3.11–3.14，以及 macOS、Windows 的最低与最高支持版本；Linux/Python 3.14 还执行风格、类型与分发检查。本地结果只代表实际运行的环境。覆盖率用于分析，没有强制百分比门槛。
+
+## 命名与模块设计
+
+- 组合入口保持声明式：终端适配器拥有参数、交互、输出流和退出码，服务拥有应用行为，报告模块将结构化结果转为读者可理解的文本。
+- 模块以其职责命名。Python 使用 `snake_case`，类型使用 `PascalCase`，JSON 键遵守既有模式。稳定 ID 与路径独立于中文展示名。
+- 在有意义的边界使用带类型的值对象。优先扩展现有所有者，避免泛化工具层、可变全局注册表和没有消费者的兼容别名。
+- 按数据所有权、生命周期或失败策略拆分模块；不为行数或表面整齐制造层级。
+- 区分精确观察、候选、启发式与未解析关系。可选能力缺口可降级，漂移、损坏和无效契约必须阻止错误结果继续传播。
+- 在能解释异常的边界捕获预期异常，保留异常原因。面向用户说明失败对象、当前结果与恢复动作，不以笼统成功掩盖部分失败。
+- 写入需证明所有权、路径约束与并发行为。逐文件原子性不等于批量事务回滚。
+
+## 注释与文档语言
+
+默认使用简体中文编写 CLI 提示、维护文档和面向用户的知识。新增或实质修改的注释、文档字符串优先用中文说明**为何如此、边界是什么、失败时谁负责**；不要逐句复述代码。现有解析算法中的英文技术说明可在相关模块改动时逐步整理，外部协议、术语与原始诊断保留必要拼写。
+
+[README.md](README.md)是默认中文入口，[英文版](READMEs/README.en.md)是明确独立的翻译版。安装、命令或支持范围变化时同步维护两者。
+
+语言边界遵循以下规则：
+
+| 内容 | 约定 |
+| --- | --- |
+| 帮助、确认、预览、进度、恢复建议 | 简体中文 |
+| 新创作的知识与生成的工作区导航 | 默认简体中文；用户明确指定其他语言时遵从 |
+| 命令、参数、路径、slug、源码标识 | 保持原样 |
+| JSON 字段、枚举状态、诊断码与摘要 | 保持机器契约；说明文本可使用中文 |
+| 多语言检索词、Unicode 测试数据、第三方错误细节 | 保留原始含义，不机械翻译 |
+
+帮助从实际注册参数生成；命令语义放在 `command_reference.py`，通用交互放在 `cli_commands/presentation.py`，分析展示放在 `cli_commands/analysis_display.py`，协议值显示名放在 `display_labels.py`。不得修改 Click/Typer 的全局类、私有常量或整段替换用户输出。
+
+`src/modus/scaffold/templates/` 是随包交付的产品契约，Python 直接读取这些资源，不另存一份竞争性正文规范。其[本地化约定](src/modus/scaffold/templates/skills/using-modus/references/authoring/framework/localization.md)规定默认语言与局部修订边界。
+
+设计规则放在负责它的文档中，其他指南通过链接引用。文件名保持稳定、含义明确。创作设计与安装后的参考必须同步更新；相对链接和命令示例会按仓库与真实 CLI 注册情况检查。
+
+## 测试与扩展
+
+参见[测试地图](tests/README.md)。行为修复应覆盖有意义的成功、失败及用户数据保留场景。避免对偶然句式、辅助函数结构或输出长度做质量断言；语言回归可以检查中文语义与协议稳定性。
+
+新增平台需覆盖安装、幂等、共享文件、升级、用户修改保护与卸载。新增语言需覆盖声明、实现版本、观察结果与缺失工具链降级。模式或公开 CLI 变更需说明兼容性影响并更新文档。只在安装后才可能暴露的问题放入产物与运行时冒烟检查。
+
+迭代时执行最小相关检查，提交前跑完整验证。明确说明未执行的检查与原因，不把本地验证表述为跨平台 CI 已通过。

{openmodus-0.0.3 → openmodus-0.0.4}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: openmodus
-Version: 0.0.3
-Summary: Evidence-backed authored knowledge for coding agents.
+Version: 0.0.4
+Summary: 为编程助手构建有证据支撑、可持续维护的项目知识。
 Author: Modus contributors
 License-Expression: MIT
 License-File: LICENSE
@@ -76,6 +76,7 @@ Description-Content-Type: text/markdown
 
 [![PyPI](https://img.shields.io/pypi/v/openmodus?label=PyPI&color=3775A9)](https://pypi.org/project/openmodus/)
 ![Python](https://img.shields.io/badge/Python-3.11%E2%80%933.14-3776AB?logo=python&logoColor=white)
+<!-- NOCA:AllFileLicenseCheck(项目许可声明与根目录协议及包元数据一致) -->
 [![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 [**简体中文**](README.md) · [English](READMEs/README.en.md)
@@ -94,22 +95,42 @@ Modus 将源码与业务材料梳理成可核验的项目知识库，让 Coding
 
 ---
 
+<!--
+产品价值与命令能力对应，维护宣传语时核对当前可执行入口。
+-->
+
 ## 核心功能
 
 Modus 把项目知识作为可维护的工程资产：本地分析提供线索，Agent 与人确认业务含义，Markdown 承载长期结论，日常任务按需使用并随变更修订。
 
+<!--
+证据地图说明观察能力，不代表机器已经完成业务知识创作。
+-->
+
 ### 从证据建立项目地图
 
 初始化时，本地分析从源码、构建上下文和可用工具链提取有界证据，帮助定位入口、关系与关键行为。Agent 再回读源码、测试、配置和业务材料，确认系统架构、领域边界与真实场景，将判断写入系统概览、领域、模块及专题文档。
 
+<!--
+上下文预算与降级共同约束检索结果，完整性描述必须保留这一前提。
+-->
+
 ### 为任务渐进装配上下文
 
 开发、排障或评审需要项目事实时，Agent 从系统概览进入相关领域、模块与场景，按需联读团队约束，并回到当前源码核验。检索按问题组织知识和实现片段，明确标示证据缺口；日常使用直接读取仓库中的 Markdown 与当前源码，无需重跑初始化分析。
 
+<!--
+评审链路依赖普通Markdown与版本控制，不能暗示独立的远端知识服务。
+-->
+
 ### 让知识进入代码评审链路
 
 长期知识以 Markdown 与代码同仓保存。稳定的领域与模块身份、知识链接和结构化源码锚点形成追溯路径；人工维护的业务知识与团队约束有明确所有权，完整性检查负责结构、链接和锚点，让知识变更具有清晰的评审边界。
 
+<!--
+维护触发点是长期语义变化，临时实现细节不应沉淀为团队规则。
+-->
+
 ### 随长期语义变化精确维护
 
 代码变更后，Agent 根据本次修改判断职责、契约、规则、状态、依赖、资源或源码锚点是否发生长期变化；确有影响时，在原定义处修订受影响正文并同步相关导航与引用。新增业务材料和局部事实也可以定向更新，使知识随项目演进而保持可用。
@@ -118,6 +139,10 @@ Modus 把项目知识作为可维护的工程资产：本地分析提供线索
 
 从源码安装 CLI，接入目标仓库，再由 Agent 基于项目证据创建第一份知识。CLI 负责平台接入；经确认的 Markdown 才是留在仓库中的长期产物。
 
+<!--
+安装示例与分发包元数据同步；命令名和Python包名具有不同职责。
+-->
+
 ### 1. 安装 CLI
 
 在 Modus 源码仓库根目录（包含 `pyproject.toml`），使用 [`uv`](https://docs.astral.sh/uv/) 安装 CLI（需要 Python 3.11–3.14）：
@@ -128,6 +153,10 @@ uv tool install .
 
 也可以从 PyPI 安装发布包：`uv tool install openmodus`。参与 Modus 开发时，使用 `uv tool install --editable .` 可让源码修改直接生效。无论安装来源，命令都是 `modus`。其他安装方式与索引配置见[安装与接入选项](#安装与接入选项)。
 
+<!--
+接入过程仅写入框架拥有的资产，用户正文的保护边界保持可见。
+-->
+
 ### 2. 接入项目
 
 进入要使用 Modus 的项目仓库：
@@ -139,6 +168,10 @@ modus init
 
 在交互式终端中选择 Claude Code、Codex、Cursor 或 CodeBuddy。CLI 将平台中立的 Skill 与命令安装到项目，再通过对应适配器接入所选平台，并记录受管文件的所有权。脚本接入、多平台接入和安装状态检查见[安装与接入选项](#安装与接入选项)。
 
+<!--
+知识创作入口与后续维护入口分开说明，避免将重建作为日常前置。
+-->
+
 ### 3. 创建项目知识
 
 在所选 Coding Agent 中打开该项目，在对话中运行：
@@ -153,6 +186,10 @@ modus init
 
 ## 为什么需要 Modus
 
+<!--
+能力表描述项目已实现的范围，缺失提供方与降级应如实表述。
+-->
+
 ### 你会得到什么
 
 接手一个项目时，找到代码入口只是开始：还需要弄清规则为何存在、什么结果算完成、失败后如何恢复，以及改动要守住哪些边界。Modus 把经源码和可用业务材料核验的长期结论留在仓库，让后续任务从已有理解出发，并继续以当前源码核对实现。
@@ -170,6 +207,10 @@ modus init
 
 Modus 需要 Python 3.11–3.14，安装后的命令是 `modus`。下面按平台与语言列出可用范围。
 
+<!--
+平台支持列表与安装验收一起维护，不能以模板存在代替平台验证。
+-->
+
 #### Coding Agent 平台
 
 <p align="center">
@@ -181,6 +222,10 @@ Modus 需要 Python 3.11–3.14，安装后的命令是 `modus`。下面按平
 
 每个适配器声明自己的 Skill 目录、常驻说明和 Hook 布局；共享安装器负责确定性写入、所有权清单、升级合并与安全卸载。
 
+<!--
+语言识别、结构解析和编译器证据是不同能力，不合并为统一精度承诺。
+-->
+
 #### 语言能力
 
 不同语言的证据深度明确分层，不以“识别文件后缀”冒充完整语义支持。
@@ -266,6 +311,10 @@ Modus 把一次性机器分析与长期知识明确分开：`init/reinit` 负责
 
 以一个需要修改订单回调重试行为的项目为例：在覆盖范围内，初始化证据可指向回调入口、状态写入及相关源码，但“重复通知应返回什么”仍需作者回读实现、测试和可用的业务约定。确认后，幂等条件、失败恢复和验证入口按各自职责写入 Module 与规则、状态专题。下一位开发者沿 Domain、Module 找到这些结论，核对当前源码后动手；若改动改变了重试契约或状态迁移，就原位修订相应主定义和引用，内部重构则无需增加知识。
 
+<!--
+知识模型区分稳定身份与展示名称，翻译不能改变协议键。
+-->
+
 ### 知识模型
 
 完成项目知识创作后，`.modus/` 保存平台控制面，`modus/knowledge/` 保存长期知识，`modus/.cache/` 保存可丢弃的分析状态。Modus 的知识模型不是一棵按文件类型堆积的文档树，而是围绕研发任务组织的四种可组合视角。它们是阅读和建模视角，不是要求每个项目复制同一种技术分层。
@@ -310,6 +359,10 @@ modus/knowledge/
 
 Modus 优先显式化**高复用、高风险、高隐性**的知识，而不是为每个函数生成摘要。公开契约、核心对象、状态流转、下游交接、兼容红线和验证标准值得长期维护；从当前代码即可低成本读出的普通实现细节仍留在源码中。`business/` 与 `constraint/` 默认受人工所有权保护，自动流程不会用扫描结果覆盖组织经验；生成知识的变更使用读时哈希保护，并接受路径身份、链接与锚点完整性核验。
 
+<!--
+架构解释围绕输入、所有权与失败语义，图示跟随真实依赖方向。
+-->
+
 ### 代码架构
 
 Modus 自身也遵守它倡导的边界：入口层保持窄，应用编排与检索算法分离，平台差异通过声明式适配器收口，长期知识与一次性分析状态拥有不同的目录和写入合同。
@@ -339,6 +392,10 @@ Modus 自身也遵守它倡导的边界：入口层保持窄，应用编排与
 
 接入后在目标仓库运行 `modus status`：显示 `Installation: installed`（已安装）表示项目资产已就位。CLI 会在 `modus/knowledge/` 放置初始文件，仍需在 Agent 中运行 `/modus-init` 创作正文；`status` 的知识文档数也会计入初始文件，不能单独作为创作完成的依据。
 
+<!--
+命令手册与CLI注册同步，示例保留真实参数与退出语义。
+-->
+
 ### CLI 命令
 
 CLI 用于安装、维护和检查 Modus。运行 `modus help` 可以查看当前版本的完整入口。
@@ -388,9 +445,13 @@ modus uninstall --person --dry-run
 
 日常使用时，直接向 Agent 提出具体任务，例如“检查订单回调的重复通知与重试规则，找到实现和验证入口，并修复已确认的问题”。Agent 按需沿概览、Domain 和 Module 读取相关知识，再用当前源码核验；若本次修改改变了长期契约、规则、状态或源码锚点，交付前才修订对应正文。你也可以从 `architecture-overview.md` 沿链接手动阅读，遇到文档与实现不一致时以当前源码为准，再定向修订知识。
 
+<!--
+开发步骤应能由新环境复现，本地通过不等于全部平台已经验证。
+-->
+
 ## 开发与贡献
 
-先阅读[架构导览](ARCHITECTURE.md)了解依赖方向与设计边界，再按[贡献指南](CONTRIBUTING.md)运行检查。开发文档与 CLI 提示统一使用英文。
+先阅读[架构导览](ARCHITECTURE.md)了解依赖方向与设计边界，再按[贡献指南](CONTRIBUTING.md)运行检查。CLI 帮助、交互提示、诊断、开发文档及新创作知识默认使用简体中文。命令名、参数、路径和 JSON 字段保持稳定，便于脚本与工具集成。
 
 Modus 支持 Python 3.11–3.14。开发环境和 CI 使用同一组锁定依赖与质量门禁：
 
@@ -407,4 +468,5 @@ uv run --locked --extra test mypy
 
 ### License
 
+<!-- NOCA:AllFileLicenseCheck(项目许可声明与根目录协议及包元数据一致) -->
 Modus 使用 [MIT License](LICENSE)。

{openmodus-0.0.3 → openmodus-0.0.4}/README.md

@@ -27,6 +27,7 @@
 
 [![PyPI](https://img.shields.io/pypi/v/openmodus?label=PyPI&color=3775A9)](https://pypi.org/project/openmodus/)
 ![Python](https://img.shields.io/badge/Python-3.11%E2%80%933.14-3776AB?logo=python&logoColor=white)
+<!-- NOCA:AllFileLicenseCheck(项目许可声明与根目录协议及包元数据一致) -->
 [![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 [**简体中文**](README.md) · [English](READMEs/README.en.md)
@@ -45,22 +46,42 @@ Modus 将源码与业务材料梳理成可核验的项目知识库，让 Coding
 
 ---
 
+<!--
+产品价值与命令能力对应，维护宣传语时核对当前可执行入口。
+-->
+
 ## 核心功能
 
 Modus 把项目知识作为可维护的工程资产：本地分析提供线索，Agent 与人确认业务含义，Markdown 承载长期结论，日常任务按需使用并随变更修订。
 
+<!--
+证据地图说明观察能力，不代表机器已经完成业务知识创作。
+-->
+
 ### 从证据建立项目地图
 
 初始化时，本地分析从源码、构建上下文和可用工具链提取有界证据，帮助定位入口、关系与关键行为。Agent 再回读源码、测试、配置和业务材料，确认系统架构、领域边界与真实场景，将判断写入系统概览、领域、模块及专题文档。
 
+<!--
+上下文预算与降级共同约束检索结果，完整性描述必须保留这一前提。
+-->
+
 ### 为任务渐进装配上下文
 
 开发、排障或评审需要项目事实时，Agent 从系统概览进入相关领域、模块与场景，按需联读团队约束，并回到当前源码核验。检索按问题组织知识和实现片段，明确标示证据缺口；日常使用直接读取仓库中的 Markdown 与当前源码，无需重跑初始化分析。
 
+<!--
+评审链路依赖普通Markdown与版本控制，不能暗示独立的远端知识服务。
+-->
+
 ### 让知识进入代码评审链路
 
 长期知识以 Markdown 与代码同仓保存。稳定的领域与模块身份、知识链接和结构化源码锚点形成追溯路径；人工维护的业务知识与团队约束有明确所有权，完整性检查负责结构、链接和锚点，让知识变更具有清晰的评审边界。
 
+<!--
+维护触发点是长期语义变化，临时实现细节不应沉淀为团队规则。
+-->
+
 ### 随长期语义变化精确维护
 
 代码变更后，Agent 根据本次修改判断职责、契约、规则、状态、依赖、资源或源码锚点是否发生长期变化；确有影响时，在原定义处修订受影响正文并同步相关导航与引用。新增业务材料和局部事实也可以定向更新，使知识随项目演进而保持可用。
@@ -69,6 +90,10 @@ Modus 把项目知识作为可维护的工程资产：本地分析提供线索
 
 从源码安装 CLI，接入目标仓库，再由 Agent 基于项目证据创建第一份知识。CLI 负责平台接入；经确认的 Markdown 才是留在仓库中的长期产物。
 
+<!--
+安装示例与分发包元数据同步；命令名和Python包名具有不同职责。
+-->
+
 ### 1. 安装 CLI
 
 在 Modus 源码仓库根目录（包含 `pyproject.toml`），使用 [`uv`](https://docs.astral.sh/uv/) 安装 CLI（需要 Python 3.11–3.14）：
@@ -79,6 +104,10 @@ uv tool install .
 
 也可以从 PyPI 安装发布包：`uv tool install openmodus`。参与 Modus 开发时，使用 `uv tool install --editable .` 可让源码修改直接生效。无论安装来源，命令都是 `modus`。其他安装方式与索引配置见[安装与接入选项](#安装与接入选项)。
 
+<!--
+接入过程仅写入框架拥有的资产，用户正文的保护边界保持可见。
+-->
+
 ### 2. 接入项目
 
 进入要使用 Modus 的项目仓库：
@@ -90,6 +119,10 @@ modus init
 
 在交互式终端中选择 Claude Code、Codex、Cursor 或 CodeBuddy。CLI 将平台中立的 Skill 与命令安装到项目，再通过对应适配器接入所选平台，并记录受管文件的所有权。脚本接入、多平台接入和安装状态检查见[安装与接入选项](#安装与接入选项)。
 
+<!--
+知识创作入口与后续维护入口分开说明，避免将重建作为日常前置。
+-->
+
 ### 3. 创建项目知识
 
 在所选 Coding Agent 中打开该项目，在对话中运行：
@@ -104,6 +137,10 @@ modus init
 
 ## 为什么需要 Modus
 
+<!--
+能力表描述项目已实现的范围，缺失提供方与降级应如实表述。
+-->
+
 ### 你会得到什么
 
 接手一个项目时，找到代码入口只是开始：还需要弄清规则为何存在、什么结果算完成、失败后如何恢复，以及改动要守住哪些边界。Modus 把经源码和可用业务材料核验的长期结论留在仓库，让后续任务从已有理解出发，并继续以当前源码核对实现。
@@ -121,6 +158,10 @@ modus init
 
 Modus 需要 Python 3.11–3.14，安装后的命令是 `modus`。下面按平台与语言列出可用范围。
 
+<!--
+平台支持列表与安装验收一起维护，不能以模板存在代替平台验证。
+-->
+
 #### Coding Agent 平台
 
 <p align="center">
@@ -132,6 +173,10 @@ Modus 需要 Python 3.11–3.14，安装后的命令是 `modus`。下面按平
 
 每个适配器声明自己的 Skill 目录、常驻说明和 Hook 布局；共享安装器负责确定性写入、所有权清单、升级合并与安全卸载。
 
+<!--
+语言识别、结构解析和编译器证据是不同能力，不合并为统一精度承诺。
+-->
+
 #### 语言能力
 
 不同语言的证据深度明确分层，不以“识别文件后缀”冒充完整语义支持。
@@ -217,6 +262,10 @@ Modus 把一次性机器分析与长期知识明确分开：`init/reinit` 负责
 
 以一个需要修改订单回调重试行为的项目为例：在覆盖范围内，初始化证据可指向回调入口、状态写入及相关源码，但“重复通知应返回什么”仍需作者回读实现、测试和可用的业务约定。确认后，幂等条件、失败恢复和验证入口按各自职责写入 Module 与规则、状态专题。下一位开发者沿 Domain、Module 找到这些结论，核对当前源码后动手；若改动改变了重试契约或状态迁移，就原位修订相应主定义和引用，内部重构则无需增加知识。
 
+<!--
+知识模型区分稳定身份与展示名称，翻译不能改变协议键。
+-->
+
 ### 知识模型
 
 完成项目知识创作后，`.modus/` 保存平台控制面，`modus/knowledge/` 保存长期知识，`modus/.cache/` 保存可丢弃的分析状态。Modus 的知识模型不是一棵按文件类型堆积的文档树，而是围绕研发任务组织的四种可组合视角。它们是阅读和建模视角，不是要求每个项目复制同一种技术分层。
@@ -261,6 +310,10 @@ modus/knowledge/
 
 Modus 优先显式化**高复用、高风险、高隐性**的知识，而不是为每个函数生成摘要。公开契约、核心对象、状态流转、下游交接、兼容红线和验证标准值得长期维护；从当前代码即可低成本读出的普通实现细节仍留在源码中。`business/` 与 `constraint/` 默认受人工所有权保护，自动流程不会用扫描结果覆盖组织经验；生成知识的变更使用读时哈希保护，并接受路径身份、链接与锚点完整性核验。
 
+<!--
+架构解释围绕输入、所有权与失败语义，图示跟随真实依赖方向。
+-->
+
 ### 代码架构
 
 Modus 自身也遵守它倡导的边界：入口层保持窄，应用编排与检索算法分离，平台差异通过声明式适配器收口，长期知识与一次性分析状态拥有不同的目录和写入合同。
@@ -290,6 +343,10 @@ Modus 自身也遵守它倡导的边界：入口层保持窄，应用编排与
 
 接入后在目标仓库运行 `modus status`：显示 `Installation: installed`（已安装）表示项目资产已就位。CLI 会在 `modus/knowledge/` 放置初始文件，仍需在 Agent 中运行 `/modus-init` 创作正文；`status` 的知识文档数也会计入初始文件，不能单独作为创作完成的依据。
 
+<!--
+命令手册与CLI注册同步，示例保留真实参数与退出语义。
+-->
+
 ### CLI 命令
 
 CLI 用于安装、维护和检查 Modus。运行 `modus help` 可以查看当前版本的完整入口。
@@ -339,9 +396,13 @@ modus uninstall --person --dry-run
 
 日常使用时，直接向 Agent 提出具体任务，例如“检查订单回调的重复通知与重试规则，找到实现和验证入口，并修复已确认的问题”。Agent 按需沿概览、Domain 和 Module 读取相关知识，再用当前源码核验；若本次修改改变了长期契约、规则、状态或源码锚点，交付前才修订对应正文。你也可以从 `architecture-overview.md` 沿链接手动阅读，遇到文档与实现不一致时以当前源码为准，再定向修订知识。
 
+<!--
+开发步骤应能由新环境复现，本地通过不等于全部平台已经验证。
+-->
+
 ## 开发与贡献
 
-先阅读[架构导览](ARCHITECTURE.md)了解依赖方向与设计边界，再按[贡献指南](CONTRIBUTING.md)运行检查。开发文档与 CLI 提示统一使用英文。
+先阅读[架构导览](ARCHITECTURE.md)了解依赖方向与设计边界，再按[贡献指南](CONTRIBUTING.md)运行检查。CLI 帮助、交互提示、诊断、开发文档及新创作知识默认使用简体中文。命令名、参数、路径和 JSON 字段保持稳定，便于脚本与工具集成。
 
 Modus 支持 Python 3.11–3.14。开发环境和 CI 使用同一组锁定依赖与质量门禁：
 
@@ -358,4 +419,5 @@ uv run --locked --extra test mypy
 
 ### License
 
+<!-- NOCA:AllFileLicenseCheck(项目许可声明与根目录协议及包元数据一致) -->
 Modus 使用 [MIT License](LICENSE)。