# agentWorkSpace

**Repository Path**: pluto-charon77/agent-work-space

## Basic Information

- **Project Name**: agentWorkSpace
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-15
- **Last Updated**: 2026-05-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# pluto AgentWorkspace

`pluto-AgentWorkspace` 是一个用于统一接入、分析、维护多个业务代码仓库的 AI 协作工作区。它本身不是业务应用，也不承载线上运行服务；它更像是一个“仓库管理与智能分析中枢”，负责放置 AI 助手规则、项目扫描脚本、仓库文档、协作约束和 Git 工作流规范。

当前工作区已经初始化为 Git 仓库，并支持同时推送到多个远程代码平台，例如 GitHub、Gitee、阿里云云效等。业务项目通过克隆或软链接方式接入到 `repositories/` 目录，由工作区脚本统一识别和分析。

## 项目定位

本项目主要解决以下问题：

1. 多个业务仓库分散在不同目录、不同平台，缺少统一入口。
2. AI 助手在多仓库环境中容易混淆目标仓库、误提交或误推送。
3. 项目文档、模块文档、辅助函数文档需要统一的生成和维护规范。
4. 不同 AI 工具需要一致的仓库规则、Git 操作规则和协作流程。
5. 本地已有项目不希望移动位置，但仍希望纳入统一扫描和分析。

因此，本工作区的核心职责是：

- 统一接入业务仓库。
- 统一维护 AI 助手规则。
- 统一生成和维护项目级文档。
- 统一约束跨仓库 Git 操作边界。
- 统一沉淀仓库分析、模块分析、Helper 分析等自动化能力。

## 当前接入仓库

当前工作区通过软链接方式接入了以下业务项目：

| 项目 | 工作区路径 | 原始路径 | 说明 |
| --- | --- | --- | --- |
| app-template | `repositories/app-template` | `/Users/pluto/Desktop/project/GitHub/app-template` | 钢小信跨端客户端 |
| jiangxin | `repositories/jiangxin` | `/Users/pluto/Desktop/project/GitHub/jiangxin` | 江信供应链 CRM/ERP 后台及会员 API |
| jiangxin-app | `repositories/jiangxin-app` | `/Users/pluto/Desktop/project/GitHub/jiangxin-app` | 江信 CRM 移动端与企微 H5 |
| jiangxin-external-app-admin | `repositories/jiangxin-external-app-admin` | `/Users/pluto/Desktop/project/GitHub/jiangxin-external-app-admin` | 钢小信管理端 |

这些目录在 Git 中被忽略，不会随本工作区提交。工作区只管理 AI 规则、脚本和公共文档结构，不直接托管业务仓库源码。

## 整体架构

```text
pluto-AgentWorkspace/
├── .agents/                     # Codex / Agent 使用的本地技能和规则
│   └── skills/
├── .claude/                     # Claude Code 使用的技能和规则
│   └── skills/
├── docs/                        # 工作区文档入口与项目文档目录
│   ├── DOCS.md                  # 文档导航和开发流程说明
│   └── {project-name}/          # 项目级文档目录，当前默认忽略提交
├── repositories/                # 业务仓库接入目录，支持 clone 或软链接
├── scripts/                     # 自动化分析和接入脚本
│   ├── repo-analyzer/           # 仓库接入与仓库级扫描
│   ├── module-analyzer/         # 模块级文档扫描
│   ├── helper-analyzer/         # Helper / Util / Hook 文档扫描
│   └── mcp-mysql-setup/         # MCP MySQL 配置辅助脚本
├── AGENTS.template.md           # 可提交的本地 AI 规则模板
├── AGENTS.md                    # Codex 工作规则入口，本地生效且默认不提交
├── CLAUDE.md                    # Claude 工作规则和仓库概览
├── CLAUDE_template.md           # Claude 规则模板
├── README.md                    # 当前文件，面向维护者的项目说明
└── .gitignore                   # Git 忽略规则
```

## 核心目录说明

### `repositories/`

业务代码仓库统一接入目录。

接入方式有两种：

1. 远程克隆：将远程 Git 仓库 clone 到 `repositories/{project-name}`。
2. 本地软链接：将本机已有项目目录软链接到 `repositories/{project-name}`。

软链接方式适合已有项目固定在其他路径的场景。对于扫描脚本来说，只要软链接目标是合法 Git 仓库，效果与 clone 到 `repositories/` 基本一致。

### `docs/`

工作区文档目录。

根文件 `docs/DOCS.md` 是文档导航入口，说明文档结构、仓库接入方式和开发流程。

项目级文档约定放在：

```text
docs/{project-name}/
```

常见文件包括：

```text
docs/{project-name}/repository.md
docs/{project-name}/modules/README.md
docs/{project-name}/modules/{Module}.md
docs/{project-name}/helpers/README.md
```

当前 `.gitignore` 已配置忽略 `docs/*/`，因此项目扫描生成的子目录文档不会默认提交，只保留 `docs/` 根目录下的入口文件进入版本控制。

### `scripts/`

自动化脚本目录。

主要脚本：

| 脚本 | 作用 |
| --- | --- |
| `scripts/repo-analyzer/repo-analyzer.js` | 接入项目，支持 Git clone 或本地软链接 |
| `scripts/repo-analyzer/repo-analyze.js` | 对已接入仓库进行仓库级分析，维护 `CLAUDE.md` 和 `docs/{project}/repository.md` |
| `scripts/module-analyzer/module-analyzer.js` | 扫描项目模块，生成或更新 `docs/{project}/modules/` 文档 |
| `scripts/helper-analyzer/helper-analyzer.js` | 扫描公共 Helper、Util、Hook、Composable 等辅助代码 |
| `scripts/mcp-mysql-setup/index-claude.js` | Claude 侧 MCP MySQL 配置辅助脚本 |
| `scripts/mcp-mysql-setup/index-opencode.js` | OpenCode 侧 MCP MySQL 配置辅助脚本 |
| `scripts/mcp-mysql-setup/index-codex.js` | Codex App 侧 MCP MySQL 配置辅助脚本 |

仓库分析、模块分析和 Helper 分析脚本会调用本机的 Claude CLI 进行代码阅读和文档生成，因此运行前需要确保 `claude` 命令可用。MCP 配置脚本主要负责写入对应工具的本地配置文件。

### `.agents/` 和 `.claude/`

用于存放不同 AI 工具的本地技能和协作规则。

当前包含 Git 仓库操作相关技能，用于在多仓库场景下识别目标仓库、约束 Git 写操作、生成规范 commit 消息，并避免跨仓库误操作。

### `AGENTS.md`

Codex 使用的工作规则入口。

其中规定了：

- 当前工作区的定位。
- 业务仓库接入位置。
- 文档目录约定。
- 编码前必须阅读的文档顺序。
- 模块文档处理策略。
- Git 操作约束。

`AGENTS.md` 是本地实际生效文件，默认不提交到远程仓库。新成员应复制 `AGENTS.template.md` 生成自己的本地规则文件：

```bash
cp AGENTS.template.md AGENTS.md
```

首次初始化时，建议让 AI 助手询问当前接入仓库、目录结构、项目特殊注意事项、远程仓库和忽略规则，并据此更新本地 `AGENTS.md`。

### `CLAUDE.md`

Claude Code 使用的工作规则和仓库概览。

仓库级扫描脚本会维护此文件中的项目列表、技术栈和简要说明。

## 快速开始

### 1. 克隆或进入工作区

```bash
cd /Users/pluto/Desktop/project/GitHub/pluto-AgentWorkspace
```

### 2. 查看当前接入仓库

```bash
node scripts/repo-analyzer/repo-analyze.js --list
```

该命令会扫描 `repositories/` 下所有包含 `.git` 的目录或软链接目标。

### 3. 通过软链接接入本地项目

```bash
node scripts/repo-analyzer/repo-analyzer.js --link /path/to/local/project
```

脚本会根据本地目录名创建 `repositories/{project-name}` 软链接，并可选择立即执行仓库级分析。

也可以手动创建软链接：

```bash
ln -s /path/to/local/project repositories/project-name
```

手动软链接后，可通过以下命令确认是否被识别：

```bash
node scripts/repo-analyzer/repo-analyze.js --list
```

### 4. 克隆远程仓库接入

```bash
node scripts/repo-analyzer/repo-analyzer.js git@example.com:group/project.git
```

脚本会将仓库克隆到 `repositories/{project-name}`，并可继续执行分析。

### 5. 执行仓库级扫描

扫描指定项目：

```bash
node scripts/repo-analyzer/repo-analyze.js app-template
```

列出可扫描项目：

```bash
node scripts/repo-analyzer/repo-analyze.js --list
```

仓库级扫描会维护：

```text
CLAUDE.md
docs/{project-name}/repository.md
```

注意：当前 `docs/*/` 被 Git 忽略，扫描生成的项目子目录文档不会默认提交。

### 6. 执行模块扫描

```bash
node scripts/module-analyzer/module-analyzer.js
```

该脚本会交互式选择项目，也支持扫描全部项目。它会分析业务模块、模块关系、API、数据流和核心业务流程，并维护：

```text
docs/{project-name}/modules/
```

### 7. 执行 Helper 文档扫描

```bash
node scripts/helper-analyzer/helper-analyzer.js
```

该脚本会扫描公共辅助代码，例如：

- helper
- util / utils
- hook
- composable
- global 方法
- 公共工具对象

输出位置：

```text
docs/{project-name}/helpers/README.md
```

## AI 协作流程

在处理业务仓库代码前，应遵循以下顺序：

1. 阅读 `docs/DOCS.md`。
2. 阅读目标项目的 `docs/{project-name}/repository.md`。
3. 如果任务涉及业务模块，先确认模块文档处理策略。
4. 使用 `rg`、Glob、Grep 等工具搜索真实源码。
5. 在用户明确选择的目标仓库内完成代码修改。
6. 根据变更同步更新对应文档。

模块文档处理策略有三种：

1. 先阅读相关模块文档，再搜索源码。
2. 跳过模块文档，直接搜索源码。
3. 跳过模块文档，直接搜索源码，并在任务完成后补充或更新模块文档。

该流程的目标是兼顾文档优先和真实代码优先，避免因为文档滞后造成误判。

## Git 工作流

### 本工作区 Git 仓库

当前工作区本身已经是一个 Git 仓库，用于管理：

- AI 助手规则。
- 分析脚本。
- 工作区文档入口。
- 协作流程说明。
- 忽略规则和模板文件。

当前远程仓库：

```bash
github  https://github.com/pluto-charon67/agentWorkSpace.git
gitee   git@gitee.com:pluto-charon77/agent-work-space.git
```

可以分别推送：

```bash
git push github main
git push gitee main
```

当前 `main` 分支默认跟踪 `gitee/main`。如果直接执行 `git push`，默认会推送到 Gitee；推送 GitHub 时应显式指定远端。

### 多远端策略

同一个本地仓库可以配置多个远端：

```bash
git remote add github <github-url>
git remote add gitee <gitee-url>
git remote add aliyun <aliyun-codeup-url>
```

不同平台、不同账号建议通过 SSH Host 别名隔离。例如：

```sshconfig
Host github-work
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_github_work

Host gitee-work
  HostName gitee.com
  User git
  IdentityFile ~/.ssh/id_ed25519_gitee_work

Host codeup-aliyun
  HostName codeup.aliyun.com
  User git
  IdentityFile ~/.ssh/id_ed25519_aliyun_codeup
```

然后远端地址可以写成：

```bash
git remote add github git@github-work:owner/repo.git
git remote add gitee git@gitee-work:owner/repo.git
git remote add aliyun git@codeup-aliyun:owner/repo.git
```

### 业务仓库 Git 操作约束

业务仓库位于 `repositories/` 下，可能是 clone 目录，也可能是软链接目录。

执行以下 Git 写操作前，必须先确认目标仓库：

- `git add`
- `git commit`
- `git push`
- 会改写历史或工作树的操作

禁止在未确认目标仓库时跨仓库批量提交或推送。

## Git 忽略规则

当前 `.gitignore` 主要规则：

```gitignore
.DS_Store
repositories/*/
!repositories/.gitkeep
repositories/app-template
repositories/jiangxin
repositories/jiangxin-app
repositories/jiangxin-external-app-admin
docs/*/
.mcp.json
opencode.json
```

含义：

- `repositories/*/`：忽略 `repositories/` 下通过 clone 接入的业务仓库目录。
- `!repositories/.gitkeep`：保留 `repositories/` 目录，使远程仓库中也能看到该目录。
- `repositories/app-template` 等具体项：忽略当前通过软链接接入的业务仓库。Git 会将目录软链接视为文件项，因此需要显式忽略。
- `docs/*/`：忽略 `docs/` 下的项目子目录文档，仅保留 `docs` 根目录文件。
- `.mcp.json`：忽略可能包含敏感信息的 MCP 配置。
- `opencode.json`：忽略可能包含敏感信息的 OpenCode 本地配置。
- `.DS_Store`：忽略 macOS 系统文件。

如果未来希望提交某个项目的文档子目录，需要调整 `.gitignore`，或使用更细粒度的白名单规则。

## 文档维护规范

项目级文档统一放在：

```text
docs/{project-name}/
```

常见维护规则：

| 修改内容 | 建议更新文档 |
| --- | --- |
| 新增或修改 API 接口 | `docs/{project-name}/modules/{Module}.md` |
| 新增或修改类方法 | `docs/{project-name}/modules/{Module}.md` |
| 新增或修改数据结构 | `docs/{project-name}/modules/{Module}.md` |
| 新增模块间调用 | `docs/{project-name}/modules/{Module}.md` 和 `docs/{project-name}/modules/README.md` |
| 修改业务流程 | `docs/{project-name}/modules/{Module}.md` |
| 新增或修改公共辅助函数 | `docs/{project-name}/helpers/README.md` |
| 修改仓库结构或代码规范 | `docs/{project-name}/repository.md` |

## 常用命令

查看远端：

```bash
git remote -v
```

查看工作区状态：

```bash
git status --short --branch
```

查看可分析仓库：

```bash
node scripts/repo-analyzer/repo-analyze.js --list
```

分析指定仓库：

```bash
node scripts/repo-analyzer/repo-analyze.js <repo-name>
```

软链接接入本地仓库：

```bash
node scripts/repo-analyzer/repo-analyzer.js --link /path/to/project
```

生成模块文档：

```bash
node scripts/module-analyzer/module-analyzer.js
```

生成 Helper 文档：

```bash
node scripts/helper-analyzer/helper-analyzer.js
```

配置 Codex App 的 MySQL MCP：

```bash
node scripts/mcp-mysql-setup/index-codex.js
```

该脚本默认写入 `~/.codex/config.toml`，会自动备份原配置，并写入 `mcp_server_mysql` 的 MCP Server 配置。配置完成后通常需要重启 Codex App 才能加载新 MCP。

验证 Codex 是否能实际调用 MySQL MCP：

```bash
codex exec --skip-git-repo-check --json "请只使用可用的 MySQL MCP 工具查询：SELECT 1 AS ok。不要使用 shell、node、python、mysql 客户端或读取配置文件。若没有 MySQL MCP 工具，请直接回答没有。"
```

如果返回事件中出现 `mcp_tool_call`，且 `server` 为 `mcp_server_mysql`、`tool` 为 `mysql_query`，说明 Codex 已经能实际调用该 MCP。建议在本地 `AGENTS.md` 中补充数据库查询约束，要求 AI 在数据库查询任务中优先使用 MCP，避免绕到临时脚本。

推送到 GitHub：

```bash
git push github main
```

推送到 Gitee：

```bash
git push gitee main
```

## 注意事项

1. `repositories/` 下的业务仓库不会提交到当前工作区仓库。
2. `docs/{project-name}/` 当前默认忽略提交，适合存放扫描生成的本地项目文档。
3. 运行扫描脚本前，需要确保本机已安装并登录 Claude CLI。
4. 仓库级扫描、模块扫描、Helper 扫描都可能读取大量源码，耗时取决于项目规模。
5. 对业务仓库执行 Git 写操作前，必须明确目标仓库，避免误提交到其他项目。
6. 当前工作区可以推送到多个远端，但直接 `git push` 会使用当前分支 upstream。
7. 涉及账号、token、MCP、本地工具配置的文件不应提交到仓库。
8. 如果软链接目标目录移动或删除，`repositories/` 下的链接会失效，需要重新创建。
9. 如果远端平台使用不同账号，推荐使用 SSH Host 别名和独立 SSH key 隔离身份。
10. 如果需要让 AI 助手修改业务代码，应先确认目标仓库和模块文档处理策略。

## 项目维护建议

- 将根目录 `README.md` 作为人类维护入口。
- 将 `AGENTS.md` 作为 Codex 等 AI 助手的强约束入口。
- 将 `CLAUDE.md` 作为 Claude Code 的仓库认知入口。
- 将 `docs/DOCS.md` 作为文档体系入口。
- 将 `scripts/` 中的脚本作为仓库接入、扫描和文档生成的统一工具。
- 尽量保持工作区仓库轻量，不混入业务源码、密钥、本机配置和临时生成物。