# carlos-flow-cindy 中文文档

规范地址：https://npmcn.com/package/carlos-flow-cindy/

版本：2\.5\.1
npm 元数据更新时间：2026-11-03T06:51:52.523Z
中文译文更新时间：2026-11-03T07:04:46.957Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/carlos-flow-cindy
原文对照：https://npmcn.com/package/carlos-flow-cindy/?lang=original
项目主页：https://github.com/skyer-now/carlos-flow-cindy#readme
源码仓库：https://github.com/skyer-now/carlos-flow-cindy

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：100 kB，16 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.0\.0
- 运行依赖：1 个
- 首次发布：2026-11-03T06:49:14.888Z
- 最新版本发布：2026-11-03T06:51:52.279Z
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

Carlos 工作流 MCP - Cindy 适配版（自动管理 Bridge，内置密钥库集成）

## 安装

```sh
npm install carlos-flow-cindy
```

也可以使用：`pnpm add carlos-flow-cindy`、`yarn add carlos-flow-cindy`、`bun add carlos-flow-cindy`

## README

# Carlos 工作流 - Cindy 适配版

> 机械门禁 MCP：留痕 → 派发 → 裁定 → 审计 → 快照还原 自动管理 Bridge 后台常驻，首次调用 ~3-5s，后续复用 ~1s

## ✨ 特性

-   **零配置启动**：首次调用自动拉起 Bridge，无需手动运行后台进程
-   **Cindy 原生集成**：通过 `ghost.json` 声明，插件设置页可视化配置环境变量
-   **密钥库保护**：Bridge Token 等敏感信息存入 Cindy 加密保险库，代码不含明文
-   **全平台支持**：Windows / macOS / Linux 均可运行（需 Node.js 22+）
-   **完整门禁流程**：12 个工具覆盖 T0/T1/T2 三档路由、四段合同、独立复核、审计链

## 📦 安装

### 方式一：Cindy 插件市场（推荐）

1.  打开 Cindy → 设置 → 插件 → 浏览市场
2.  搜索 `carlos-flow` 点击安装
3.  在插件设置页填写 `CARLOS_FLOW_MCP_ROOT` 和 `CARLOS_FLOW_HOME`
4.  重启 Cindy，输入 `/门禁` 或在对话中直接说“走门禁”

### 方式二：本地源码安装

```bash
# 1. 克隆仓库
git clone https://github.com/skyer-now/carlos-flow-cindy.git
cd carlos-flow-cindy

# 2. 安装依赖
npm install

# 3. 配置环境变量（复制模板并修改）
cp .env.example .env
# 编辑 .env 填入你的实际路径

# 4. 验证安装
npm test          # 冒烟测试（隔离临时目录）
npm run test:e2e  # 端到端测试（需配置好环境变量）
```

## ⚙️ 环境变量

| 变量 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- |
| `CARLOS_FLOW_MCP_ROOT` | ✅ | MCP 源码根目录（含 `src/`、`bridge/`、`client/`） | `D:/cindy/carlos-flow-mcp` |
| `CARLOS_FLOW_HOME` | ✅ | 状态/审计/快照根目录 | `~/carlos-flow` |
| `BRIDGE_PORT` | ❌ | Bridge 监听端口（默认 19099） | `19099` |
| `REA_MCP_ROOT` | ❌ | rea MCP 源码根目录 | `D:/dev-env/rea` |
| `GHIDRA_HOME` | ❌ | Ghidra 安装目录 | `D:/dev-env/ghidra/ghidra_12.1.4_PUBLIC` |
| `JAVA_HOME` | ❌ | JDK 21 安装目录 | `D:/dev-env/jdk-21.0.12.1+1` |
| `NODE_PATH` | ❌ | Node.js 可执行文件路径（默认 `node`） | `node` |

> **提示**：Cindy 插件设置页修改环境变量后需**完全退出 Cindy 重启**生效。

## 🛠️ 可用工具（12 个）

| 工具 | 作用 |
| --- | --- |
| `flow_protocol` | 读取完整协议文档 |
| `flow_add_user_msg` | 写入用户原话（锚点数据源） |
| `flow_submit_requirement` | 提交任务卡（留痕 + 校验） |
| `flow_claim` | 领取派发名额（executor/auditor） |
| `flow_dispatch` | 生成派发 prompt + 文件快照 |
| `flow_verdict` | 记录裁定（PASS/DIRECTION/LOCAL） |
| `flow_status` | 查询门禁状态 |
| `flow_audit` | 读取审计流水 |
| `flow_diff_hunks` | git diff hunk 分析 |
| `flow_bypass` | 免检开关 |
| `flow_save_result` | 保存子 Agent 结果 |
| `flow_revert_plan` | 生成还原计划 |

## 🔄 工作流示例

```mermaid
flowchart TD
    A[用户需求] --> B[flow_add_user_msg 写入原话]
    B --> C[flow_submit_requirement 留痕]
    C --> D[flow_claim executor]
    D --> E[flow_dispatch 生成快照+prompt]
    E --> F[子 Agent 执行]
    F --> G[flow_save_result 保存结果]
    G --> H[flow_claim auditor]
    H --> I[flow_dispatch 复核]
    I --> J[flow_verdict 裁定]
    J --> K{PASS?}
    K -->|是| L[完成]
    K -->|否| M[返工/方向调整]
```

## 🧪 测试

```bash
# 冒烟测试（完全隔离，不污染真实数据）
npm test

# 端到端测试（需配置好 CARLOS_FLOW_MCP_ROOT 等环境变量）
npm run test:e2e

# rea 真实 Ghidra 分析测试（需配置 GHIDRA_HOME/JAVA_HOME）
npm run test:rea
```

## 📁 目录结构

```
carlos-flow-cindy/
├── src/                    # MCP Server 核心（stdio 传输）
│   ├── index.js            # 入口：注册 12 个工具
│   ├── protocol.js         # 协议定义（路由表/合同/错误层/状态 schema）
│   ├── card.js             # 任务卡解析/修复/校验
│   ├── state.js            # 状态持久化/审计链/用户消息源
│   └── dispatch.js         # 四段合同/文件快照/结果保存
├── bridge/                 # TCP Bridge（安全桥接层）
│   ├── mcp-bridge.js       # 监听 127.0.0.1:19099，Token 认证、限流、超时控制
│   └── health.js           # /health 端点（就绪探测）
├── client/                 # CLI 客户端
│   ├── carlos.js           # 自动管理 Bridge 生命周期
│   └── rea.js              # rea 自包含客户端
├── test/                   # 测试套件
│   ├── smoke.js            # 冒烟测试（临时目录隔离）
│   ├── e2e-carlos.mjs      # 16 项端到端用例
│   └── e2e-rea.mjs         # 8 项 rea Ghidra 真实分析
├── ghost.json              # Cindy 插件清单
├── settings.html/js        # 插件设置页
├── .env.example            # 环境变量模板
├── package.json
└── README.md
```

## 🔒 安全设计

-   **Bridge 仅监听 127.0.0.1**，拒绝外部连接
-   **Token 认证**：每请求携带 `CARLOS_BRIDGE_TOKEN`，错误即拒绝
-   **限流**：单连接 10 req/s，防止误刷
-   **请求体上限**：1 MB，防止内存耗尽
-   **审计链 SHA-256**：每条记录含 `prevHash`/`hash`，防篡改可验证

## 📄 许可证

MIT License - 详见 [LICENSE](https://npmcn.com/package/carlos-flow-cindy/LICENSE)

## 🤝 贡献

欢迎 PR！请先跑通 `npm test` 和 `npm run test:e2e`。

* * *

**从 OpenCode 版迁移？** 请看 [carlos-flow-opencode](https://github.com/skyer-now/carlos-flow-opencode) —— 纯 stdio 传输，无 Bridge，配置走 `.mcprc`/`opencode.json`。

## 常见问题

### carlos-flow-cindy 是什么？

Carlos 工作流 MCP - Cindy 适配版（自动管理 Bridge，内置密钥库集成）

### 如何安装 carlos-flow-cindy？

在项目目录运行 npm install carlos-flow-cindy，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 carlos-flow，可以用 npx carlos-flow 直接运行。

### carlos-flow-cindy 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/carlos-flow-cindy 是否存在。

### carlos-flow-cindy 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### carlos-flow-cindy 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### carlos-flow-cindy 可以商用吗？

carlos-flow-cindy 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### carlos-flow-cindy 还在维护吗？

最新版本 2\.5\.1 发布于 2026/11/03（今天）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/11/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。