# 跨工具协作

**Repository Path**: ai-tools_666/cross-tool-collaboration

## Basic Information

- **Project Name**: 跨工具协作
- **Description**: 每个 agent 是独立的上下文孤岛：切走即失忆，新 agent 不知道上一个做了什么、做过什么决定、卡在哪个待决点上。
没有单一事实来源：设计系统的决策散落在各 agent 的对话里，没有一个「交付物 + 约定」的固定落点。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-02
- **Last Updated**: 2026-09-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# cross-tool-collaboration — ncollab 多 agent 协作工作区

> **N 工具可扩展协作模型**：以「共享项目目录 = 单一事实来源」的协议与 CLI，让多个异构 AI 工具稳定协作、可追溯、可扩展第 N 个工具。

本仓库既是该模型的**落地实现**，也是它的**真实运行现场**——仓库本身由多个 agent 按 ncollab 协议共同维护。

## 核心特性

- **上下文恢复**：每个 agent 切走后可通过精简快照（约 200 token）恢复上下文，二次入场自动进行 git/文件指纹增量
- **决策追溯**：设计决策通过决策日志与交接契约固定落点，事后可完整追溯
- **异构协同**：支持任意数量、任意厂商的 agent 接入同一套协议，**无需安装 git 即可使用**
- **协作闭环**：标准化的入场、加锁、落盘、决策、交接、放锁、校验流程

## 快速开始

### 环境要求

- Python 3.8+（用于 ncollab CLI）
- Vite（用于工作台前端）
- Git（可选，CLI 会自动降级处理）

### 安装方式

**方式一：npx 一键安装**

```bash
npx skills add ncollab
```

**方式二：手动安装**

```bash
git clone https://github.com/AIToolTheta/cross-tool-collaboration.git
cd cross-tool-collaboration/release/ncollab
pip install -e .
```

### 核心命令

```bash
# 入场：恢复上下文
ncollab snapshot --agent <your-agent>

# 加锁：获取任务写锁
ncollab lock <your-agent> --task N

# 决策：记录决策（协调者权限）
ncollab decision ...

# 交接：离场交接
ncollab handoff --agent <your-agent>

# 放锁：释放任务锁
ncollab unlock <your-agent>

# 校验：检查协作状态
ncollab check
```

## 仓库结构

```
cross-tool-collaboration/
├── AGENTS.md            # Agent 注册清单：能力/拥有文件/协作级别/入口流程
├── PROJECT.md           # 项目规格（单一事实来源）
├── TASKS.md             # 任务队列（todo/in-progress/done）
├── DECISIONS.md         # 决策日志（D-001 ~ D-011）
├── HANDOFF.md           # 交接契约（离场必写，入场先读）
├── tokens.json          # 设计 tokens（W3C DTCG，dark/light 双套）
├── 设计稿/               # 组件库/工作台页面/tokens 预览页
├── src/                 # Vite + ESM 工作台骨架，UI 一律读取 tokens.json
├── go-to-market/        # 渠道/变现/结算调研 + 落地页 + 专业版审计日志设计
├── release/             # 独立发布子仓库 release/ncollab（v2.2.0）
├── docs/                # 操作记录等存档文档
├── .lock/               # 协作写锁（一次一个写）
└── package.json         # 工作台依赖（Vite，ESM）
```

## 协作模型

### 已注册角色

| 角色 | 能力 | 拥有文件（写） | 协作级别 |
|------|------|----------------|----------|
| 协调者（Coordinator） | 调研/文案/协议主理 | PROJECT/TASKS/HANDOFF/DECISIONS/AGENTS | A 全自主 |
| 设计（Designer） | 设计/tokens | tokens.json, 设计稿/ | A 全自主 |
| 代码（Developer） | 代码/git | src/, package.json | A 全自主 |

### 协作级别说明

- **A 全自主**：锁 + 落盘 + commit
- **B 仅文件**：读写目录但不可 git
- **C 纯对话**：代写/代提交

### 无 git 降级

当环境没有 git 时，系统自动降级为文件指纹（md5）增量管理，并使用 `ncollab backup` 进行版本备份（保留 20 份历史版本）。

## 技术栈

- **ncollab CLI**：Python 3.8+，纯标准库单文件实现
- **工作台**：Vite + ESM，UI 颜色/字号/间距一律读取 tokens.json，禁止硬编码
- **版本管理**：git（有则用）；无 git 环境自动降级为 backup

## 相关文档

| 文档 | 位置 |
|------|------|
| 发布版 README（安装/快速开始/CLI 速查） | `release/ncollab/README.md` |
| 完整协议规范（文件 schema/锁/权限） | `release/ncollab/skill/references/protocol.md` |
| 提交推送记录（2026-09-10 历史改写） | `docs/2026-09-10-提交推送记录.md` |

## 版本与发布

- **当前版本**：v2.2.0
- **发布仓库**：`release/ncollab` 子仓库
- **许可证**：MIT
- **发布平台**：GitHub + Skills.sh（Vercel 官方技能市场）

## 项目状态

| 维度 | 状态 |
|------|------|
| 竞品调研 | ✅ 已完成 |
| 设计 tokens | ✅ 已完成 |
| src 骨架 | ✅ 已完成 |
| 决策记录 | ✅ D-001 ~ D-011 已定 |

## 参与贡献

本项目采用 ncollab 协作模型，欢迎按照协议规范接入新的 agent 角色。详细协议规范请参阅 `release/ncollab/skill/references/protocol.md`。