# 知习 (ZhiXi) 项目

AI 驱动的系统化学习平台，包含 6 个子项目。

| 目录 | 项目 | 技术栈 | 负责 Agent |
|------|------|--------|-----------|
| `startup-plan/` | 项目规划、技术设计、任务记录 | Markdown | Global Agent |
| `api-server/` | 后端 API | NestJS + TypeScript + Prisma + MySQL + Redis | Backend Agent |
| `ios-projects/AIStudyApp/` | iOS App | SwiftUI + 深色主题 | iOS Agent |
| `web-projects/` | Web 官网 | Astro + Tailwind CSS v4 | Web Agent |
| `devops-projects/` | 运维、服务器、凭据 | SSH/Docker/Nginx | DevOps Agent |
| `admin-projects/` | 管理后台 | 待开发 | Web Agent 兼管 |

每个子项目的 `README.md` 是唯一项目文档（人类 + AI 共用），底部有 "For AI Agents" 章节。

## Agent View 工作流

Agent 配置在 `.claude/agents/` 下。

### 全局工作流

1. 用户 → Global Agent（分析任务、拆解、列决策点）
2. 用户确认 → Global Agent 分发子任务到专业 Agent
3. 专业 Agent 执行 → **小任务直接在对话中完成**，复杂/跨模块任务写入 AI_xxx_WORKSPACE.md
4. Global Agent 汇总（读取有变更的 WORKSPACE）→ 写入 AI_GLOBAL_WORKSPACE.md
5. Global Agent 调用 `@review-agent` 触发审查
6. Review 通过 → Global Agent 给出 commit message 建议
7. 用户确认 → git add / commit / push
8. Global Agent 将本轮摘要归档到 `已完成/` → 清空所有 WORKSPACE

### 任务分级

| 级别 | 示例 | WORKSPACE 流程 |
|------|------|---------------|
| **小任务** | 单文件修改、颜色调整、文案修正 | 跳过，对话闭环 |
| **中任务** | 单项目多文件、单接口新增 | 专业 Agent 写入自己的 WORKSPACE |
| **大任务** | 跨模块、多 Agent 协作 | 完整流程，所有 WORKSPACE 联动 |

Global Agent 在分析任务时判断级别。

### 文件所有权

同一文件不允许两个 Agent 同时修改。Global Agent 分发任务时必须标注：
- 每个子任务允许修改的文件列表
- 如有文件冲突，按优先级排队（优先级由用户确认）

### 错误回滚

用户可随时说"取消本轮"。Global Agent 收到后：
1. 清空所有 AI_xxx_WORKSPACE.md 填写内容
2. 不回填已完成目录
3. 恢复模板状态，等待下一轮

### 权限和边界

| Agent | 负责范围 | 禁止 |
|-------|---------|------|
| Global Agent | startup-plan，分析/分发/汇总 | 默认不改业务代码 |
| Backend Agent | api-server | 不能私自新增未确认的接口/字段/表 |
| iOS Agent | ios-projects | 不能改后端，不能自行发明接口 |
| Web Agent | web-projects | 不能改后端，不能自行发明接口 |
| DevOps Agent | devops-projects，服务器/部署/CICD | 不能改业务代码 |
| Review Agent | 全局只读审查 | 不能改代码，不能 git 操作 |

### 跨模块规则

1. 专业 Agent 遇到跨模块问题，只能反馈给 Global Agent
2. 专业 Agent 不允许私自新增接口、字段、数据库表、部署服务
3. iOS/Web Agent 缺接口时，在对话或 WORKSPACE 中写"需要后端支持"
4. Backend Agent 需要数据库/部署/前端决策时，在对话或 WORKSPACE 中写阻塞反馈
5. 所有跨模块决策必须由 Global Agent 汇总后交用户确认
6. 接口事实以后端真实代码和 OpenAPI 为准

### Review 触发

Global Agent 在所有子任务完成后，显式调用：
```
@review-agent 审查 [scope] 本轮变更
```

Review Agent 将结果写入对应 WORKSPACE 或直接回复 Global Agent。

### Git 规则

1. 专业 Agent 不允许主动 git commit / push
2. Review Agent 不允许 git commit / push
3. Global Agent 只能在 Review 通过后给出建议 commit message
4. 只有用户明确说"提交"后，才可执行 git 操作
5. 提交完成后清空所有 WORKSPACE 本轮内容

### 提交后归档

Global Agent 在提交成功后：
1. 将本轮摘要写入对应项目的 `startup-plan/技术设计/[project]/已完成/` 目录
2. 文件名格式：`YYYY-MM-DD-简短描述.md`
3. 然后清空所有 WORKSPACE

## 服务器

| 名称 | 公网 IP | 内网 IP | 厂商 | 凭据 |
|------|--------|--------|------|------|
| 轻量云 | 81.70.187.179 | 10.2.0.7 | 腾讯云 | `devops-projects/凭据配置/轻量云服务器凭据.md` |
| 蜂驰云 | 120.53.227.155 | 172.21.0.4 | 腾讯云 CVM | `devops-projects/凭据配置/蜂驰云服务器凭据.md` |

内网已通过云联网 CCN 打通。

## 如何启动

```bash
claude --agent-view
```

或在 Claude Code 中输入 `/agents`。
