内容
="center">
<img src="assets/logo.png"ArchSmith logo" width="420">
</p>
# ArchSmith 是一个本地优先的工程记忆插件和 MCP重用已批准的代码，而不是要求 AI 代理重新创建。
它在您的机器上存储已批准的函数、、配方、版本历史和重用日志。MCP进行网络调用。默认情况下，数据存储在：
```text
%USERPROFILE%\.codex\archsmith
```
AI 编程代理在重新生成用户项目中已时，会花费大量输出令牌。ArchSmith 改变工作流程：
1. 保存一个函数一次。
2显式批准它。
3. 稍后按名称重用或实现它。
4. 仅当归一化差异在配置的突变阈值内时，才适应小项目特定细节。
默认突变阈值为 `20%`。较大的更改成为新的候选项，需要显式批准。
## 预先批准的ArchSmith 被设计为预先批准的工程记忆。
这意味着代理不应将存储的函数视为模糊的建议或对话笔记。只有在函数被显式提出、审查和，它才能成为可重用的记忆。一旦批准，代理就可以在不花费令牌重构相同实现的情况下，检索其合约、元数据、版本和本地源文件。
这使 Arch接近于本地批准构建块目录，而不是通用记忆系统：
- 按名称、上下文和版本重用已批准的代码；
- 除非需要检查，否则存储的代码不会打印到聊天中；
- 仅在突变阈值内允许小适应较大的更改成为新的候选项，需要批准；
- 重用在本地记录，以便历史记录可审计。
## ArchSmith 提供- 一个用于用户、配置文件、知识领域、模块、修订和重用日志的本地 SQLite 存储。
- 一个名为 `archsmith-mcp` 的_stdio MCP 服务器。
- 一个名为 `archsmith` 的 Codex 插件，带有 `memory` 技能。
- 用于直接重用的低令牌工具：
- `archsmith_recommend_reuse`
- `archize_by_name`
- `archsmith_plan_project`
- `archsmith_materialize_project`
- `archsmith_estimate_savings`
- `archsmith_estimate_project_savings`
- 用于常见重用、推荐、项目创建和批准工作流的 MCP 提示。
- 用于上下文和已批准函数的元数据 MCP 资源。
- 可重用代码的优先。
- 本地路径验证和路径遍历保护。
化目标的可选 `ARCHSMITH_ALLOWED_ROOTS` 强制执行。
- 拒绝类似机密的内容，例如、令牌、cookie、私钥和完整的连接字符串。
ArchSmith 带有预加载的记忆、示例数据库和捆绑的项目数据。
## 安装
### 要求
- Python 3.10 或更新版本。
- stdio MCP 服务器的客户端，例如 Codex、Cl 或 opencode。
### 独立 MCP
克隆并将您的 MCP 客户端指向服务器：
```bash
git clone https://github.com/HendrylHH.git
cd archsmith
```
```json
{
mcpServers": {
"archsmith-mcp "command": "python",
"args"/absolute/path/to/plugins/archsmith/mcp/server.py", "--stdio"],
"env": {
"PYTHONDBYTECODE": "1",
"PYTHONUN": "1"
}
}
}
}
Windows 上，使用绝对路径，例如：
```json
{
"mcpServers": {
"archsmith-mcp": {
"command": "python",
"args": ["D:\\path\\to\\plugins\\archsmith\\mcp\\server.py", "--stdio"],
"env": {
"PYTHONDONTWRITEBYTECODE": "1",
"PYTHONUNBUFFERED": "1"
}
}
}
}
```
### Claude Code 插件
ArchSmith 可以作为 Claude Code 插件安装。该插件捆绑了相同的本地 stdio MCP 服务器，因此 Claude Code 可以在启用插件时自动启动它。
在 Claude Code 中，添加此存储库作为插件市场并安装 ArchSmith：
```text
/plugin marketplace add HendrylHH/archsmith
archsmith@archsmith
/reload-plugins
```
检查捆绑的 MCP 服务器是否已连接：
```text
/mcp
```
安装后，Claude Code 应从插件提供的服务器公开 ArchSmith 的 MCP 工具。例如，低令牌路径仍为 `archsmith_materialize_by_name`，只是通过 Claude Code 的 MCP 工具命名公开。
对于本地开发，您可以直接从存储库根目录加载插件：
```bash
claude --plugin-dir ./plugins/archsmith
```
如果您不想安装插件，仍然可以直接添加 MCP 服务器：
```bash
claude mcp add --transport stdio archsmith -- python /absolute/path/to/plugins/archsmith/mcp/server.py --stdio
```
### Codex 插件
该存储库包含一个市场文件 `.agents/pluginsplace.json` 和插件源 `plugins/archsmith`。
克隆后：
```bash
codex plugin marketplace add /absolute/path/to/archsmith
codex plugin add archsmith@archsmith
```
然后启动新的 Codex 线程，以便加载 MCP 工具和技能元数据。
## CLI 如果您的客户端不在会话中公开 MCP 工具，请使用捆绑的 CLI。
为任务推荐已批准的函数：
```bash
python plugins/archsmith/mcp/cli.py --task "Create a billing import script from approved functions" \
--profile "Company X" \
--knowledge 123"
```
实现一个已批准的函数```bash
python plugins/archsmith/mcp/cli.py function_name \
--destination /path/to/project \
confirm-write \
--record-reuse \
-- --client codex
```
在不编写的情况下，对一个已批准的函数进行干预运行：
```bash
python plugins/archsmith/mcp/cli.py materialize function_name \
--destination /path/to/project \
--dry --minimal
```
估计一个已批准的函数的
```bash
python plugins/archsmith/mcp/cli function_name \
--destination /path/to/project
```
从多个已批准的函数创建项目：
```bash
python plugins/archsmith/mcp/cli.py plan-project \
--spec /path/to/project-spec.json
```
然后在审查后实现：
```bash
python plugins/archsmith/mcp/cli.py project \
--spec /path/to/project-spec.json \
--confirm-write \
--record-reuse \
--minimal \
--client codex
```
估计项目级别的节省：
```bash
python plugins/archsmith/m estimate-project \
--spec /path/to/project
```
## 聊天提示示例
与启用编码代理一起使用类似的提示：
- “使用 ArchSmith 推荐哪些已批准的函数可用于公司 123 中的新计费协调脚本。仅选项和原因，不显示存储的代码。”
- “使用 ArchSmith 创建一个包含已保存函数 `load_company_settings`、`normalize_customer_record` 和 `write_project_report` 的新脚本，用于公司 X 的项目 123。将公司标签从 `Company X` 更改为 `Company Y`, 只需在生成的脚本中更改。”
- “使用 ArchSmith 将公司 X 的计费工具包中的已批准函数 `parse_b 实现到此项目中。记录重用，不在聊天中打印存储的代码。”
- “从公司 X 的目录化 ArchSmith 函数 `read_job_manifest`、`prepare_output_dir`、`build_batch_summary`、`write_json_ 和 `format_status_line` 中创建一个新项目。常量从 `output` 到 `artifacts`。”
- “在公司 X / 项目 123 中搜索与报告相关的已批准的 Python 函数。仅显示摘要和签名；仅在我选择一个时加载代码。”
- “提出当前实现作为可重用的 ArchSmith 函数，位于用户 公司 X / 项目 123 / 报告下，但在已批准之前请等待我的批准。”
## 如何选择重用
ArchSmith 对已经知道其重复工作的人员和团队最有用，并且可以决定保存哪些内容以供重用。MCP 不会爬取代码库或神奇地推断出每个或您的团队批准的函数，附加元数据，并批准修订。
当下一个任务到达时，`archsmith_recommend_reuse` 通过仅查看已批准的元数据来帮助代理选择候选项：
- 完全匹配函数名称或 slug；
- 匹配上下文，例如用户、公司/配置文件、项目/知识和模块；
- 语言和标签匹配；
- 任务术语存在于名称、摘要、签名、标签和上下文名称中；
- 批准的最近性和重用历史。
推荐工具返回 `ready`、`ambiguous`、`needs_context` 或 `not_found`。它还返回原因和下一个操作，但绝不会返回存储的代码。如果上下文太广泛，代理应该询问用户意图哪个公司、项目、模块。
## 项目规范
`archsmith_materialize_project` 和 CLI `project` 命令接受一个 JSON 规范：
```json
{
"destination_path": "/path/to/new-project",
"context": {
"user": "User X",
"profile": "Company X",
"knowledge": "Operations Toolkit",
"module": "core"
},
"functions": [
"name": "load_company_settings",
" "settings.py",
"replacements": {
DEFAULT_COMPANY = \"Company X\"": "DEFAULT_COMPANY = \"Company Y\""
}
},
{
"name": "normalize_customer_record",
"filename.py"
},
{
"name": "write_project_report",
"filename": "reports.py"
}
]
}
```
替换是仅应用于已实现输出的精确字符串替换。它们不会改变已批准的存储修订。如果归一化差异超过 `20%`，ArchSmith 将阻止写入并要求新的批准版本。
## 令牌节省示例
下表使用综合函数和 ArchSmith 的本地近似标记器（`approx_regex_tokens`）。实际模型标记化有所不同，但每个比较都使用相同的方法计数。
### 场景 1：三功能项目
从 `User X / Company X / Operations Toolkit / core` 下的三个已批准的函数项目，并进行一次小替换。
| 场景 | | 总计 |
| --- | ---: | ---: | ---: |
| 使用 ArchSmith | 137 | 260 | 397 |
| 不使用 ArchSmith | 688 | 428 | 1,116 |
近似减少：`719` 个令牌，或约 `64.4%`。
### 场景 2：单个 CSV 解析器
在不打印聊天中的存储代码的情况下，实现一个已批准的计费 CSV 解析| 场景 | 输入 | 输出 | 总计 |
| --- | ---: | ---: | ---: |
| 使用 ArchSmith | 59 | 66 | 125 |
| 不使用 ArchSmith | 249 | 474 | 723 |
近似减少：`598` 个令牌，或约 `82.7%`。
### 3：五功能自动化项目
从五个已批准的函数创建一个新的自动化项目，并应用一个小的常量替换。
| 场景 | 输入 | 输出 | 总计 |
| --- | ---: | ---: | ---: |
| 使用 ArchSmith | 189 | 398 | 587 |
| 不使用 ArchSmith | 1,051 | 440 | 1,491 |
近似减少：`904` 个令牌，或约 `6%`。
已批准的函数越大，且越高，ArchSmith 节省的令牌就越多。最大的收益是避免重新生成的代码输出。
##工作流
对于开放的重用请求：
调用 `archsmith_recommend_reuse`带有任务、已知上下文、语言、标签和所需函数名称（如果有）。
2. 如果结果为 `ready`，请遵循 `suggested_action`。
3. 如果结果为 `ambiguous` 或 `needs_context`，请询问用户缺少的上下文，而不是猜4. 如果结果为 `not_found`，确认现有目录不涵盖任务后提出新函数。
对于简单的重用请求：
1. 调用 `archsmith_materialize_by_name`。
2. 传递函数名称、目标路径、上下文过滤器（如果已知）、`confirm_write=true` 和 `record_reuse=true`。
3. 除非需要检查，否则不要将存储到对话中。
对于项目请求：
1. 调用 `archsmith_plan_project`。
2计划的文件、候选修订 ID、替换差异比率、阻止的项目和令牌估计。
3. 仅在计划可接受且写入获得批准后调用 `archsmith_materialize_project`。
4. 仅对于小的项目特定更改使用 `replacements`。
5. 如果 ArchSmith 报告差异超过 `20%`，请提出新的函数版本并请求批准。
对于令牌会计：
1. 调用 `archsmith_avings` 以获取一个函数。
2. 调用 `archsmith_estimate_project_savings` 以获取一批. 不要仅为了计算令牌而手动读取代码或数据库行。
## 安全模型
- ArchSmith 默认本地优先且离线。
- MCP 服务器不进行网络调用。
- 存储的代码和元数据保留在本地数据目录下，除非用户将它们实现到项目中。
- 如果设置了 `ARCHSMITH_ALLOWED_ROOTS`，则仅允许在其中一个以分号分隔的根目录内实现。
- ArchSmith 拒绝常见的类似机密的赋值和私钥块。
- 不要存储密码、cookie、令牌、私钥或字符串。
- 存储环境变量名称、前提条件、依赖项和操作说明。
## 开发验证
从存储库根目录运行测试套件：
```python -B -m unittest discover -s plugins/archsmith/tests -v
```
测试涵盖：
- 上下文创建和查找。
- 默认情况下不显示代码的函数批准和搜索。
- 命名实现。
- 具有小替换的项目实现。
- 不写入文件的项目规划。
- 项目级令牌估计。
- 重用推荐状态和排名。
- SQLite5 搜索和备用搜索。
- `20%` 突变阈值。
- 结构化 MCP 工具错误。
- 路径遍历阻止。
- `ARCHSMITH_ALLOWED_ROOTS` 写入限制。
- stdio MCP `tools/list`、`tools/call`、`prompts/list`、`prompts/get`、`resources/list` 和 `resources/read`。
- CLI 实现、重用日志和估计。
