# zhctprompt 新手上手指南

`zhctprompt` 不是业务代码仓库，而是 `zhct` 项目的控制中心。它负责把多个业务仓库、公司知识库、产品设计资料、方案输出、任务队列、标准规范、接口资料、Docker 本地环境、手册和视频证据放在一个地方统一管理。

开发环境已部署在线文档站，可查看 Markdown 文件和 HTML 文件。IP 访问：项目根目录 `http://101.200.165.56/zhctprompt/`，Markdown 示例 `http://101.200.165.56/zhctprompt/README.md`，HTML 示例 `http://101.200.165.56/zhctprompt/operation-manuals/index.html`。域名访问：项目根目录 `https://zhctpmt.yyangpt.cn/`，Markdown 示例 `https://zhctpmt.yyangpt.cn/README.md`，HTML 示例 `https://zhctpmt.yyangpt.cn/operation-manuals/index.html`。注意：域名站点根目录已指向 `zhctprompt` 仓库，IP 站点才使用 `/zhctprompt/` 前缀；带图片的 HTML 外发前必须在线验证 HTML 和图片资源均为 200。部署说明见 `deploy/README.md`。

如果你作为管理者或项目负责人，想知道“这个项目怎么用、资料从哪里进、团队绩效怎么看”，先打开 `AI_NATIVE_PROJECT_CONTROL_CONSOLE.md` 或同名 HTML。该入口是管理者版项目控制台，把使用说明、文件夹重梳理和绩效首版看板放在一页。

如果你要把这个项目作为面向研发的 Agent 工作台，先打开 `DEVELOPMENT_AGENT_CONSOLE.md` 或同名 HTML。研发 Agent 的稳定控制入口在 `control/development-agent/`，完成前必须运行 `control/development-agent/harness/dev_agent_harness.py`。

如果你要把这个项目作为售前招投标项目测试或标书编制工作台，先打开 `PRESALES_BIDDING_LEADER_BRIEF.html` 和 `PRESALES_BIDDING_TEAM_COLLABORATION_GUIDE.html`。稳定模块入口是 `modules/presales-bidding/`，后续真实或模拟招投标项目默认放到 `modules/presales-bidding/customer-projects/<project-slug>/`，先做来源登记、要求响应矩阵、证据门禁和人审 HTML，再进入正式标书排版。

如果你是第一次接触这个项目，先记住一句话：

> 业务代码放在同级目录 `zhctproject/`，控制资料、产品设计资料和方案资料放在 `zhctprompt/`。

如果 Agent 把产品资料、设计资料或项目资料放错目录，直接让它按 `PRODUCT_DIRECTORY_RULE.md` 重新判断。这个文件是产品/设计资料目录纠偏入口，明确 `work_`、`product_`、产品线目录和过程证据目录的边界。

如果你不知道“我该给这个项目输入什么、它会怎么处理、最后会输出什么”，先读 `PROJECT_IPO_USAGE_GUIDE.md`。这个文件用 IPO 说明所有角色如何把工作放进“一总五分”蓝图：场景产品化、软件平台化、硬件体系化、AI 工程化、交付资产化。

如果你要向领导介绍 AI Native 建设成果，打开顶层 `AI_AGENT_PROJECT_INTRO_FOR_BEGINNERS.html`；如果你要让刚加入团队、还不了解 AI Agent / Prompt OS / 微盘索引 / 项目库协作的新同事实际开始协作，打开 `TEAM_AI_NATIVE_COLLABORATION_GUIDE.html`。前者是领导版成果介绍，后者是团队成员版操作说明。给人看的 HTML 放顶层；给 Agent 维护的 Markdown 真源分别在 `standards-stack/ai-engineering/AI_AGENT_PROJECT_INTRO_FOR_BEGINNERS.md` 和 `work/2026-05-25-team-ai-native-collaboration-guide/`。

本项目还是团队共享的问答和知识资产入口。任何非平凡问题、资料检索、需求澄清、方案评审、代码建议、周报复盘或管理决策，默认遵守 `standards-stack/prompt/governance/TEAM_SHARED_QA_BASELINE.md`：先补上下文包、证据等级、信源/推理深度和验证方式，再输出结论；可复用答案要沉淀到 `work*/`、`standards-stack/`、任务索引和恢复入口。

所有有意义的代码修改和文档修改，还要遵守 `standards-stack/prompt/governance/DOCUMENT_REVIEW_LEARNING_LOOP.md`：先在本控制项目留下 Markdown 记录，让 AI 能读懂上下文、证据和经验；需要人审时生成 HTML review 页面；人的反馈要拆成认可经验和否定反模式，好的进入 wiki/skill/治理规则，不好的只进入 anti-pattern 或 stop rule。

团队问答和文档讨论还要按线程形成 Markdown 训练记录。后续 Jack 和团队的可复用问答、文档讨论、Codex 线程和同事反馈，默认用 `standards-stack/agent-skills/skills/team-thread-markdown-record/SKILL.md` 写入 `work/team-learning/thread-records/YYYY-MM-DD/<thread-slug>.md`；一线程一文档，记录目标、上下文、产物、证据、验证、认可经验、否定反模式和训练提示。它面向未来团队 Agent 训练，不保存密钥、原始生产 payload 或未脱敏个人信息。

## 1. 整体目录长什么样

每个人可以把整体目录 `zhct` 放在自己电脑的任意位置，只要保持下面的相对结构一致：

```text
zhct
├── zhctprompt                 # 控制项目，本 README 所在目录
│   ├── tasks                   # 跨项目任务队列
│   ├── control                 # 项目盘点、状态快照、任务索引、验证入口
│   ├── standards-stack         # Prompt / Agent Skills / Archon 统一规范
│   ├── modules                 # 产品模块 / 项目模块 / 售前招投标模块的一级组织入口
│   ├── work                    # 跨项目工作笔记
│   ├── work_store              # store 项目资料
│   ├── work_ai_api             # ai_api 项目资料
│   ├── work_ai_store           # ai_store 项目资料
│   ├── work_ai_app             # ai_app 项目资料
│   ├── work_sch1.0new          # sch1.0new 项目专属控制资料
│   ├── work_ydysskz            # ydysskz 运动员膳食 / 智慧餐厅运动员版本控制资料
│   ├── work_qc                 # qc 项目专属控制资料
│   ├── work_food_safety        # food_safety 项目专属控制资料
│   ├── work_win_deploy_guoxin  # win_deploy_guoxin Windows 部署仓库控制资料
│   ├── work_playwright_ui_tests # Playwright UI 自动化测试仓库控制资料
│   ├── product_pingan_yunchu   # 平安云厨产品设计、方案、UI 原型和架构图资料
│   ├── work_laidisen           # 莱迪森（南京建宁中学）智慧食堂本地部署控制资料
│   ├── work_chongqing_huanwei  # 重庆环卫项目控制资料：妙雀 308 咖啡机接入
│   ├── work_miaoque_318k_payment_integration # 妙雀 318K 支付二维码参数对比与接入资料
│   ├── work_codex_video_harness # 用户操作手册视频生成工具项目控制入口
│   ├── work_company_knowledge  # 企业微信微盘派生知识库：产品/交付/开发共享索引
│   └── docker                  # 本地 Docker 运行环境
└── zhctproject                 # 业务代码仓库，不在本控制项目里复制代码
    ├── store                   # 智慧营养健康餐厅
    ├── ai_api                  # AI运动营养师 API
    ├── ai_store                # AI运动营养师 PC 端
    ├── ai_web                  # AI运动营养师 Web 端
    ├── ai_app                  # AI运动营养师 uniapp 小程序
    ├── qc                      # 智慧食堂售前轻采集系统
    ├── sxtyj                   # 科训相关后端项目
    ├── ydysskz                 # 运动员膳食 / 智慧餐厅运动员版本
    ├── food_safety             # 食品安全智慧管理云平台，sunqianqian 本机为软链
    └── win_deploy_guoxin       # 国信 Windows 部署仓库
```

不同同事电脑上的绝对路径不一样，统一记录在 `control/local-paths.md`。新增同事或新机器时，只更新这一个文件。

## 2. 新手第一天怎么上手

### 第零步：让工作区根目录也能自动读规则

如果新机器是在整体 `zhct/` 根目录打开 Codex，而不是直接进入 `zhctprompt/`，先把版本化的根目录启动模板复制到工作区根目录：

```bash
cd zhct
cp zhctprompt/control/workspace-root-AGENTS.md AGENTS.md
```

这个模板会要求 Agent 在实质问答或任务执行前先更新 `zhctprompt`：干净工作树执行 `git -C zhctprompt pull --ff-only`；本地脏改动、非 Git 目录、认证失败、网络失败或无法快进时停止报告。该行为的项目 skill 是 `standards-stack/agent-skills/skills/zhctprompt-self-update-on-qa/SKILL.md`。

本控制项目已经开启问答后自动本地提交：如果回答产生仓库文件变更，Agent 必须按 `standards-stack/agent-skills/skills/zhctprompt-qa-auto-pull-commit/SKILL.md` 完成验证、diff 检查、任务索引校验和提交前检查后，自动提交当前任务文件。该授权不包含 push、MR/PR 或强推；冲突只有在当前任务文件且可验证时才由 Agent 自行解决，否则交给人工审核。

### 第一步：先读入口文件

按这个顺序读，能最快建立项目边界：

1. `README.md`：你正在看的新手说明。
2. `PROJECT_IPO_USAGE_GUIDE.md`：给所有人的 IPO 使用说明，说明每个角色 input 什么、项目如何 process、最后 output 什么。
3. `AGENTS.md`：给 Codex / Agent 的执行规则，说明哪些事能做、哪些事要停。
4. `HEARTBEAT.md`：长任务恢复入口，告诉你最近做到哪了。
5. `tasks/QUEUE.md`：当前任务队列，Ready 是接下来能做的事。
6. `control/README.md`：控制中心怎么做项目盘点、状态刷新和验证。
7. `control/local-paths.md`：不同同事电脑上的本地目录、仓库路径和启动命令。
8. `standards-stack/README.md`：统一规范栈的入口。
9. `modules/presales-bidding/README.md`：售前招投标项目、控标参数、标书章节和证据门禁入口。

### 第二步：配置个人云效令牌和名称

首次启动项目、首次执行云效任务，或新同事第一次接手本控制项目时，必须先询问当前同事本人：

- 个人云效令牌：写入 `YUNXIAO_TOKEN`
- 个人名称：写入 `YUNXIAO_CREATOR_NAME`

配置文件只放在本地，不提交：

```bash
cd zhct/zhctprompt
mkdir -p config/local
cp config/yunxiao.env.example config/local/yunxiao.env
```

然后把本人令牌和本人名称填入 `config/local/yunxiao.env`。如果这两个字段为空，先停下来补齐，不要沿用其他同事的令牌或名称。

### 第三步：准备业务代码

如果 `zhctproject/` 还没有业务代码，进入整体目录后按仓库清单同步。清单真源是 `control/zhctproject-repositories.csv`；以后新增 `zhctproject/` 一级业务仓库，也必须先更新这个清单。

```bash
cd zhct
cd zhctprompt
./control/scripts/sync-zhctproject-repos.sh
```

该脚本会对已存在仓库执行 `git pull --ff-only`，对缺失仓库执行 `git clone`。如果目录已经存在但不是 Git 仓库，或仓库里有本地未提交改动，脚本会停止并报告，不会覆盖本地文件。

以后在 `zhct` 工作区说“拉取最新代码”“更新代码”“同步代码”，默认都按 `standards-stack/agent-skills/skills/zhctproject-repo-sync/SKILL.md` 执行整个 `zhctproject` 清单，不只拉取当前所在的单个子仓库。

### 第四步：配置本地配置文件

Docker v2.0 跑的是本地挂载的 `store` 和 `ai_api` 代码，首次启动前必须先确认两个项目的本地配置文件已经准备好。

仓库会拉到的入口文件：

- `zhctproject/store/env.php`
- `zhctproject/ai_api/env.php`

以下三份是 git 忽略的本地配置文件，拉业务代码不会自动出现，首次启动前必须从 `zhctprompt/docker/local-config-templates/` 复制真实可用配置。

`store`：

- `zhctproject/store/application/config/local/config.php`
- `zhctproject/store/application/config/local/database.php`

`ai_api`：

- `zhctproject/ai_api/.env.local`

复制真实配置：

```bash
ZHCT_ROOT=/path/to/zhct
CONFIG_SOURCE="$ZHCT_ROOT/zhctprompt/docker/local-config-templates"

mkdir -p "$ZHCT_ROOT/zhctproject/store/application/config/local"
cp "$CONFIG_SOURCE/store/application/config/local/config.php" \
  "$ZHCT_ROOT/zhctproject/store/application/config/local/config.php"
cp "$CONFIG_SOURCE/store/application/config/local/database.php" \
  "$ZHCT_ROOT/zhctproject/store/application/config/local/database.php"
cp "$CONFIG_SOURCE/ai_api/.env.local" \
  "$ZHCT_ROOT/zhctproject/ai_api/.env.local"

rg -n "__[A-Z0-9_]+__" \
  "$ZHCT_ROOT/zhctproject/store/application/config/local" \
  "$ZHCT_ROOT/zhctproject/ai_api/.env.local"
```

`local-config-templates` 是企业内部仓库里的真实配置源，复制后通常不需要再补占位符；上面的 `rg` 命令如果有输出，说明配置文件里仍有未替换项。Docker 入口脚本会把已知旧日志路径修正到 `zhctlogs/log/`，但文件本身必须先存在。

当前机器的关键配置路径记录在 `control/local-paths.md`。

### 第五步：启动本地 Docker 环境

Docker v2.0 用来在本地跑 `store` 和 `ai_api`。第一次使用请看：

- `docker/安装部署.md`：面向第一次部署的人。
- `docker/docker.md`：镜像版本、容器路径和验证命令。

常用启动命令：

```bash
cd zhct/zhctprompt/docker
chmod +x start_zhct.sh
./start_zhct.sh
```

当前机器常用启动命令：

```bash
cd /Users/lqt/work/zhct/zhctprompt/docker
HOST_PORT=80 ./start_zhct.sh
```

默认访问地址：

```text
http://127.0.0.1
http://127.0.0.1/aizhct
http://127.0.0.1:8080/#/login
http://127.0.0.1:8080/#/restaurantManagement/restaurantManagement
http://127.0.0.1:8081
http://127.0.0.1:8082
```

PC 端使用 hash 路由，页面入口必须包含 `/#/`。`http://127.0.0.1:8080/p/Restaurant/index` 是后端接口路径，不是页面入口；未登录返回 JSON `code=100` 属于正常鉴权结果。

查看前端编译日志：

```bash
# 先进入容器，再查看日志
docker exec -it zhctapp_v2_0 bash
tail -n 200 /tmp/store-static.log
tail -n 200 /tmp/store-mobile.log
tail -n 200 /tmp/store-screen.log
tail -n 200 /tmp/store-static.log.install
tail -f /tmp/store-static.log
tail -f /tmp/store-mobile.log
tail -f /tmp/store-screen.log
exit

# 不进入容器，直接在宿主机查看日志
docker exec zhctapp_v2_0 bash -lc 'tail -n 200 /tmp/store-static.log'
docker exec zhctapp_v2_0 bash -lc 'tail -n 200 /tmp/store-mobile.log'
docker exec zhctapp_v2_0 bash -lc 'tail -n 200 /tmp/store-screen.log'
docker exec zhctapp_v2_0 bash -lc 'tail -f /tmp/store-static.log'
docker exec zhctapp_v2_0 bash -lc 'tail -f /tmp/store-mobile.log'
docker exec zhctapp_v2_0 bash -lc 'tail -f /tmp/store-screen.log'
docker exec zhctapp_v2_0 bash -lc "grep -aE 'Failed to compile|ERROR|Module not found|This dependency was not found' /tmp/store-*.log"
```

当前统一使用 80 端口：

```bash
HOST_PORT=80 ./start_zhct.sh
```

如果同名容器已经存在，脚本会先校验镜像、挂载目录和端口映射；不一致时会停止并提示处理方式。需要保留旧容器并换端口并行启动时，同时指定新的 `CONTAINER_NAME`。

### 第五步：按队列做事

不要一上来直接改代码。每个任务都走这个生命周期：

```text
DEFINE -> PLAN -> BUILD -> VERIFY -> REVIEW -> SHIP
```

含义：

- DEFINE：把自然语言需求整理成目标、范围、非目标、目标项目。
- PLAN：拆成最小可验证切片，写清任务分支、验证命令和证据路径。
- BUILD：只在目标项目做代码或文档实现。
- VERIFY：跑测试、截图、手册 QC 或视频核验。
- REVIEW：检查 diff、证据、风险和回滚方式。
- SHIP：更新 `tasks/QUEUE.md`、`HEARTBEAT.md`、`control/task-index/items/<task_id>.tsv`、生成后的 `control/task-index/tasks.tsv` 和证据路径。

### 提交前固定动作

多人协作时，提交前先跑统一检查脚本：

```bash
cd zhct/zhctprompt
./control/scripts/pre_submit_check.sh --fetch
```

这个脚本只做检查，不会自动 rebase、commit 或 push。`zhctprompt` 的问答后自动提交仍必须在该脚本通过后执行；自动提交只覆盖本地 commit，不自动 push 或创建 MR/PR。它会检查：

- 当前分支和工作区状态
- 本地分支相对 upstream 是否落后或超前
- 是否还有未解决的 Git 冲突文件
- 是否残留 `<<<<<<<`、`=======`、`>>>>>>>` 冲突标记
- `control/task-index/tasks.tsv` 是否由 `items/` 正确生成
- staged / unstaged diff 是否有 whitespace 错误

如果脚本提示当前分支落后 upstream，先处理同步：

```bash
git fetch origin --prune
git rebase @{upstream}
```

有本地未提交改动时，不要盲目 rebase；先确认这些改动属于当前任务，必要时先提交、暂存或另开 worktree。

## 3. 功能模块总览

| 模块 | 位置 | 解决什么问题 |
| --- | --- | --- |
| 控制入口 | `AGENTS.md`, `HEARTBEAT.md`, `README.md` | 让人和 Agent 知道项目规则、当前进度和恢复方式。 |
| 任务队列 | `tasks/QUEUE.md` | 管理跨项目任务，区分 Ready / Blocked / Done。 |
| 项目盘点 | `control/` | 记录 010-cpt 下有哪些项目、技术栈、Git 状态、统一任务索引和验证入口。 |
| 模块入口 | `modules/` | 按产品模块和项目模块组织资料；产品模块包含 UI 和开发项目，项目模块包含微盘所有项目索引。 |
| 产品开发 IPO 使用说明 | `PROJECT_IPO_USAGE_GUIDE.md` | 告诉管理、产品、交付、开发、硬件、AI、测试等角色 input 什么、项目如何 process、最后 output 什么。 |
| 产品系统 Prompt OS 总规范 | `standards-stack/prompt/governance/ZHCTPROMPT_PRODUCT_SYSTEM_OPERATING_STANDARD.md` | 把 `zhctprompt` 定位为产品开发部 Prompt 控制项目 / 产品资产操作系统 / Agent 总控仓库，固定三条主线、证据等级、目录契约和验收机制。 |
| 五模块运行图 | `standards-stack/management/product-development-department/FIVE_MODULE_OPERATING_MAP.md` | 连接场景产品化、软件平台化、硬件体系化、AI 工程化、交付资产化的入口、索引和模板。 |
| 产品开发总蓝图 | `standards-stack/management/product-development-department/PRODUCT_DEVELOPMENT_DEPARTMENT_BLUEPRINT.md` | 先按三条主线归类，再按“一总五分”把客户场景、软件入口、硬件能力、AI 工程底座和交付资产统一到同一张图，并由总 Agent 路由到各专业 skill。 |
| 智慧食堂产品战略体系 | `standards-stack/product-strategy/smart-canteen/README.md` | 承接智慧食堂、职工营养健康、食安监管、智能硬件和 AI 能力的产品战略、产品地图、SPAN/PDC、7-2-1、路线图和绩效看板。 |
| 康比特食安方案资产体系 | `standards-stack/solution-assets/combit-food-safety/README.md` | 承接食品安全监督管理系统产品简介、竞品拆解、优秀方案结构、PDF 标准、3 页样张和正式方案资产。 |
| LLM Wiki 知识库 | `standards-stack/llm-wiki/` | 将文章、仓库、会议材料、项目证据等 raw 来源编译成可持续更新的 Markdown wiki 和可复用 skill。 |
| 团队共享问答底层基线 | `standards-stack/prompt/governance/TEAM_SHARED_QA_BASELINE.md` | 统一同事问答、资料检索、需求澄清、方案评审、代码建议和复盘的上下文、证据、反讨好、评分和验证规则。 |
| 文档 Review 学习闭环 | `standards-stack/prompt/governance/DOCUMENT_REVIEW_LEARNING_LOOP.md` | 代码和文档修改先落 Markdown，给人看生成 HTML，人审反馈再沉淀为知识、skill、反模式和团队风格学习。 |
| 标准规范 | `standards-stack/` | 统一 Prompt、Agent Skills、Archon workflow，不在每个子项目重复维护。 |
| 工作笔记 | `work*` | 存放跨项目和单项目资料、产品设计、方案输出、UI 原型、架构图、接口文档、排障记录、数据库笔记。 |
| 手册视频工具 | `work_codex_video_harness/` | `codex-video-harness` 控制入口，指向同级工具项目并沉淀团队操作手册视频 skill。 |
| 公司知识库 | `work_company_knowledge/` | 企业微信微盘派生索引，给产品人、交付人、开发人共同检索历史项目、标准产品、研发、运维、安全和交付资料。 |
| Docker 环境 | `docker/` | 提供本地容器、PHP 7.3/7.4、Nginx、路径挂载和访问入口。 |
| 证据沉淀 | `work/<date>-...`, `work_store/qa`, 测试报告路径 | 保存任务来源、验证输出、截图/视频/QC 证据。 |

## 4. 根目录文件说明

| 文件 | 作用 | 什么时候看 |
| --- | --- | --- |
| `README.md` | 新手总入口，解释项目结构和上手路径。 | 第一次进入项目、给新人交接时。 |
| `PROJECT_IPO_USAGE_GUIDE.md` | 全员 IPO 使用说明，解释每个人输入什么、项目如何处理、输出什么。 | 第一次把工作交给本项目、周会汇报、跨角色协作、交接给新同事时。 |
| `AGENTS.md` | Agent 执行规则，包含启动顺序、路径边界、生命周期、停止规则。 | 任何自动化或代码修改前。 |
| `HEARTBEAT.md` | 当前项目恢复入口，记录最近一次切片、恢复顺序、写回要求。 | 继续上次任务或长任务中断后。 |
| `control/task-index/items/` + `control/task-index/tasks.tsv` | 统一任务索引库；`items/` 是一任务一文件的真源，`tasks.tsv` 是生成的搜索总表。 | 查某个任务做了什么、代码在哪、证据在哪，同时降低多人改同一张表的冲突。 |

## 5. `tasks/` 任务队列

| 文件 | 作用 |
| --- | --- |
| `tasks/QUEUE.md` | 跨项目控制队列。Ready 里是可执行任务，Blocked 是有前置条件的任务，Done 是已完成任务和证据链接。 |

队列项不只是待办事项，合格队列项还应该写清：

- 目标项目
- 任务类型：code / manual / video / mixed
- 范围和非范围
- 验收标准
- 验证命令或证据产物
- 停止规则

## 6. `control/` 控制中心

| 文件 | 作用 |
| --- | --- |
| `control/README.md` | 控制中心说明，解释三条交付线：代码、手册、视频。 |
| `control/010-cpt-project-inventory.tsv` | 010-cpt 项目清单，记录项目路径、VCS、技术栈标记、治理文件状态。 |
| `control/current-status.tsv` | 有边界的 Git 状态快照，避免全量扫描卡死。 |
| `control/customer-branch-governance.md` | 记录客户长期稳定分支、临时修复分支、打标签上线和同步回 `master` 的规则。 |
| `control/industry-park-deployment-versions.md` | 记录产业园/平台标准环境 `store`、`ai_api` 当前部署版本、部署时间、部署用户和制品包。 |
| `control/jx206-deployment-versions.md` | 记录江西206 `store`、`ai_api` 当前维护版本、部署时间、部署用户和制品包。 |
| `control/local-paths.md` | 统一记录不同同事电脑上的本地目录、关键仓库路径和启动命令。 |
| `control/saidi-deployment-versions.md` | 记录赛迪项目 `store`、`ai_api` 等组件最新部署版本、部署时间、部署用户和制品包。 |
| `control/stzc-deployment-versions.md` | 记录首通智城 `store`、`ai_api` 当前部署版本、维护分支和流水线信息。 |
| `control/store-deployment-versions.md` | 记录 `store` 各客户环境对应分支、最新部署标签和最新部署时间。 |
| `control/validation-quickrefs.md` | 按技术栈给验证命令起点，例如 Composer、npm、Python、Gradle、Maven。 |
| `control/scripts/bounded-status.sh` | 带超时的 Git 状态刷新脚本。 |

刷新状态常用命令：

> 不同同事的状态刷新根目录见 `control/local-paths.md`。

```bash
cd zhct/zhctprompt
TIMEOUT_SECONDS=5 ./control/scripts/bounded-status.sh \
  /Users/jack/code/010-cpt \
  ./control/current-status.tsv
```

## 7. `standards-stack/` 统一规范栈

`standards-stack/` 是 Prompt、Agent Skills、Archon workflow 的单一真源。子项目需要这些规范时，应链接到这里，而不是复制一份。

### 顶层文件

| 文件 | 作用 |
| --- | --- |
| `standards-stack/README.md` | 规范栈入口，说明 prompt、agent-skills、.archon 三部分。 |
| `standards-stack/ASSOCIATION_MAP.md` | 记录 `store`、`ai_api`、`ai_store`、`ai_app` 如何映射到统一规范栈。 |
| `standards-stack/weekly-report/` | 数字技术中心 / 数科业务团队周报生成知识库和统一 Markdown 周报口径。 |
| `work/weekly-reports/` | 团队周自动汇总入口；同事按周提交 Markdown/CSV，Codex 每周五 17:30 自动生成 Markdown、CSV 和 HTML 周报。 |
| `standards-stack/management/product-development-department/` | 产品开发部管理规范、规划蓝图、源 Word、检查清单和团队复制说明。 |
| `standards-stack/ai-engineering/` | AI 工程化入口，登记 Prompt/MCP、上下文、代码索引和评估指标。 |

### `standards-stack/prompt/`

这是提示词和治理文档真相源。

| 路径 | 作用 |
| --- | --- |
| `standards-stack/prompt/README.md` | 自动生成的 Prompt 资产索引，包含完整文件清单。 |
| `standards-stack/prompt/AGENTS.md` | prompt 目录的代理规则入口。 |
| `standards-stack/prompt/AGENTS.base.md` | 仓库级代理基线规则。 |
| `standards-stack/prompt/AGENTS.project.md` | 当前项目真实路径和边界约束。 |
| `standards-stack/prompt/MODEL_CONTEXT_GUIDE.md` | 告诉模型不同任务应加载哪些最小上下文。 |
| `standards-stack/prompt/ORGANIZATION_RULES.md` | 新增 Prompt 文件时的分类和落位规则。 |
| `standards-stack/prompt/PROMPT_STANDARD.md` | Prompt 写作和结构标准。 |
| `standards-stack/prompt/COMPANY_PROJECT_STANDARD.md` | 公司项目级标准说明。 |
| `standards-stack/prompt/AI_CODE_REVIEW_CHECKLIST.md` | 代码合并前的检查清单。 |
| `standards-stack/prompt/INTEGRATION_MATRIX.md` | 外部系统和项目集成关系矩阵。 |
| `standards-stack/prompt/requirements.toml` | prompt 相关依赖或配置记录。 |
| `standards-stack/prompt/company_ai_delivery_standard_v1.docx` | AI 交付标准 Word 文档。 |

主要子目录：

| 目录 | 作用 |
| --- | --- |
| `governance/` | 任务契约、控制项目运行模型、CI、兼容性、自动化、发布治理。 |
| `features/` | 已归档的功能 Prompt 和模块化需求。 |
| `raw-requirements/` | 原始需求入口，先收原文，再整理成正式任务。 |
| `manual/` | 用户手册生成和 QC 流水线。 |
| `recording/` | 视频录制标准。 |
| `test/` | APIFox、Playwright、CI/CD、兼容性测试和问题排查 Prompt。 |
| `qa/` | QA 复盘和避雷文档。 |
| `references/` | API、合规、外部集成参考资料。 |
| `skills/` | prompt 体系内部可复用技能和领域参考。 |
| `midscene/` | 浏览器录制、页面探索和 Midscene 相关资料。 |
| `.codex/` | Codex 多代理角色、hooks、rules 和运行脚本。 |
| `.agents/` | 本地 agent skill 资产。 |
| `scripts/` | 生成索引等维护脚本。 |

几个最重要的治理文件：

| 文件 | 作用 |
| --- | --- |
| `standards-stack/prompt/governance/ZHCT_CONTROL_PROJECT_OPERATING_MODEL.md` | 控制项目运行模型，定义产品方案、代码、手册、视频等多条交付线。 |
| `standards-stack/prompt/governance/ZHCTPROMPT_PRODUCT_SYSTEM_OPERATING_STANDARD.md` | 产品系统 Prompt OS 总规范，定义三条主线、证据等级、专业 Agent 路由和验收机制。 |
| `standards-stack/prompt/governance/ZHCT_PRODUCT_DEVELOPMENT_MASTER_AGENT.md` | 产品开发总 Agent 运行契约，负责先按三条主线分流，再按“一总五分 + IPO”把任务路由到专业 skill。 |
| `standards-stack/prompt/governance/TASK_CONTRACT.md` | 任务契约模板。 |
| `standards-stack/prompt/governance/CODEX_LONG_HORIZON_OPERATIONS.md` | 长周期 Codex 执行规范。 |
| `standards-stack/prompt/governance/YUNXIAO_CODEUP_SUBMISSION_PROCESS.md` | 云效到 Codeup 的提交流程，串起 CLI 回读、分支实现、验证、提交、MR、云效回写和任务索引。 |
| `standards-stack/prompt/governance/MANUAL_AUTOMATION_STANDARD.md` | 手册自动化标准。 |
| `standards-stack/prompt/governance/PLAYWRIGHT_TEST_AGENTS_WORKFLOW.md` | Playwright Planner / Generator / Healer 测试覆盖建设流程。 |
| `standards-stack/prompt/manual/USER_MANUAL_AND_VIDEO_PIPELINE.md` | 用户手册与视频交付流水线。 |
| `standards-stack/prompt/recording/VIDEO_RECORDING_STANDARD.md` | 视频录制标准。 |

提示：`standards-stack/prompt/README.md` 是自动生成索引。如果 prompt 目录新增文件，应运行它里面记录的生成脚本刷新索引。

### `standards-stack/agent-skills/`

这里保存面向生命周期的可复用技能。

| 文件或目录 | 作用 |
| --- | --- |
| `standards-stack/agent-skills/README.md` | Agent Skills 总说明，解释 DEFINE -> SHIP 工作流。 |
| `standards-stack/agent-skills/AGENTS.md` | agent-skills 目录执行规则。 |
| `standards-stack/agent-skills/CLAUDE.md` | Claude 兼容说明。 |
| `standards-stack/agent-skills/.claude/commands/` | `/spec`、`/plan`、`/build`、`/test`、`/review`、`/ship` 等命令映射。 |
| `standards-stack/agent-skills/skills/spec-driven-development/` | 需求归一和规格驱动开发。 |
| `standards-stack/agent-skills/skills/planning-and-task-breakdown/` | 任务拆分和计划。 |
| `standards-stack/agent-skills/skills/incremental-implementation/` | 小步实现。 |
| `standards-stack/agent-skills/skills/test-driven-development/` | 测试驱动和回归。 |
| `standards-stack/agent-skills/skills/debugging-and-error-recovery/` | 排错和恢复。 |
| `standards-stack/agent-skills/skills/code-review-and-quality/` | 代码审查和质量门禁。 |
| `standards-stack/agent-skills/skills/yunxiao-wedrive-agentic-collaboration/` | 云效 + 微盘 AI 开发协作双智能体：自然语言自动路由到代码审查、项目管理/任务调度、云效、微盘或生命周期 workflow。 |
| `standards-stack/agent-skills/skills/product-development-master-agent/` | 产品开发总 Agent：先归入三条产品系统主线，再映射到“一总五分 + IPO”，最后路由到专业 skill。 |
| `standards-stack/agent-skills/skills/smart-canteen-strategy-agent/` | 智慧食堂产品战略 Agent：沉淀战略规划、产品地图、SPAN/PDC、7-2-1、路线图和绩效看板。 |
| `standards-stack/agent-skills/skills/food-safety-solution-pdf-agent/` | 康比特食安方案资产 Agent：沉淀食品安全监督管理系统方案结构、竞品拆解、PDF 标准和 3 页样张验证。 |
| `standards-stack/agent-skills/skills/evidence-classification-agent/` | 证据分级 Agent：把资料按 A/B/C/D 分级，区分确认事实、证据推导、趋势参考和战略假设。 |
| `standards-stack/agent-skills/skills/delivery-asset-agent/` | 交付资产 Agent：把战略、产品能力和证据转成售前方案、管理层材料、手册、视频脚本和复盘资产。 |
| `standards-stack/agent-skills/skills/code-simplification/` | 行为不变的简化。 |
| `standards-stack/agent-skills/skills/security-and-hardening/` | 安全加固。 |
| `standards-stack/agent-skills/skills/documentation-and-adrs/` | 文档和架构决策记录。 |
| `standards-stack/agent-skills/skills/shipping-and-launch/` | 发布、证据包和回滚建议。 |
| `standards-stack/agent-skills/skills/team-weekly-report-generation/` | 团队统一周报生成，结合通用周报 skill 与 `standards-stack/weekly-report/` 知识库。 |
| `standards-stack/agent-skills/skills/dengbao-remediation-evidence-pack/` | 等保整改复测证据包。 |
| `standards-stack/agent-skills/skills/webapp-testing/` | 本地 Web 应用验证、Playwright 截图、浏览器日志和手册/视频前置证据。 |
| `standards-stack/agent-skills/skills/git-workflow-and-commit-governance/` | Git 分支、worktree、提交、amend、push、Codeup/VWCG 任务号关联和提交前确认规则。 |
| `standards-stack/agent-skills/skills/zhctprompt-qa-auto-pull-commit/` | `zhctprompt` 问答前自动拉取最新代码，回答后验证并自动本地提交当前任务文件；冲突按可验证性决定 Agent 处理或人工审核。 |
| `standards-stack/agent-skills/skills/yunxiao-cli-interaction/` | 云效读取、创建、更新、评论、状态、工时、TestHub、里程碑和版本操作统一走 CLI/OpenAPI-backed CLI 并留证。 |
| `standards-stack/agent-skills/skills/yunxiao-smart-canteen-requirements/` | 将截图、聊天记录或简短中文需求整理并创建到 `【自研】智慧营养健康餐厅` 云效产品类需求。 |
| `standards-stack/agent-skills/references/` | 安全检查和测试模式参考。 |

### `standards-stack/.archon/`

Archon 用于把任务从云效需求、切片计划、验证、审查、发布证据串起来。

| 文件或目录 | 作用 |
| --- | --- |
| `standards-stack/.archon/README.md` | Archon 入口说明。 |
| `standards-stack/.archon/config.yaml` | Archon 配置。 |
| `standards-stack/.archon/commands/` | store 项目的 intake、slice plan、verify、review、ship、release summary 等命令。 |
| `standards-stack/.archon/workflows/` | 云效到测试、测试通过到生产的 workflow。 |
| `standards-stack/.archon/templates/` | 云效需求转任务契约模板。 |
| `standards-stack/.archon/scripts/` | 本地执行脚本。 |

## 8. `work*` 工作资料区

这些目录只放资料、证据和工作笔记，不放业务源码。

### `modules/` 产品模块和项目模块

| 文件或目录 | 作用 |
| --- | --- |
| `modules/README.md` | 产品模块 / 项目模块的一级说明。 |
| `modules/product/README.md` | 产品模块入口，统一产品方案、UI、架构图、原型和开发项目资料。 |
| `modules/product/ui/README.md` | UI 模块入口，集中蓝湖抽样源材料、当前设计规范和蓝湖 MCP/Stitch/GemDesign 入口。 |
| `modules/product/ui/lanhu-design-source/` | 从蓝湖抽样/导出的源材料，包括蓝湖项目总表、团队导出、四端设计规范和抽样截图。 |
| `modules/product/development/README.md` | 开发模块入口，按产品视角组织各开发项目资料。 |
| `modules/product/development/projects.tsv` | 开发项目索引，覆盖 `store`、`ai_api`、`ai_store`、`ai_app`、`sch1.0new`。 |
| `modules/project/README.md` | 项目模块入口，承接企业微盘内所有项目/主题索引。 |
| `modules/project/wedrive-projects/project-index.tsv` | 微盘项目索引入口，指向 `work_company_knowledge/indexes/project-index.tsv`。 |

### `work/` 跨项目资料

| 文件 | 作用 |
| --- | --- |
| `work/README.md` | 工作空间总说明，解释 `work`、`work_store`、`work_ai_api`、`work_ai_store`、`work_ai_app`、`work_qc` 的分工。 |
| `work/CONTROLLED_PROJECT_WORKSPACE_PLACEMENT.md` | 受控项目资料落位规则：代码/交付/客户控制资料进 `work_<project>`，产品/设计专项进 `product_<project>`，通用方法进 `work`，通用治理进 `standards-stack`。 |
| `work/PROJECT_DIRECTOR_NOTES.md` | 项目总监视角的跨项目摘要，说明 `zhct` 与 `aizhct` 的边界。 |
| `work/MYSQL_SCHEMA_SKILL.md` | MySQL 建表、改表、索引、SQL 落库约定。 |
| `work/ORDER_MACHINE_REQUIREMENT_DESIGN.md` | 点餐机相关需求设计资料。 |
| `work/2026-05-03-awesome-codex-skills-intake.md` | 导入 `webapp-testing` skill 的证据。 |
| `work/2026-05-03-playwright-test-agents/` | Playwright Test Agents 文章、流程、验证证据。 |

### `work_store/` 智慧营养健康餐厅资料

| 文件或目录 | 作用 |
| --- | --- |
| `work_store/README.zhct-notes.md` | store 项目长期阅读理解摘要，包含入口、模块、接口、QA 经验。 |
| `work_store/api-docs/README.md` | store 已整理接口文档索引。 |
| `work_store/api-docs/getMeal.md` | `/p/api/getMeal` 获取当餐菜谱。 |
| `work_store/api-docs/orderPay.md` | `/api/consume/orderPay` 消费机订单结算。 |
| `work_store/api-docs/shopOrder.md` | `/api/shop/order` 外部商户订单结算，当前用于江西206售卖柜刷码结算。 |
| `work_store/api-docs/orderMachine.md` | 点餐机餐厅与档口接口。 |
| `work_store/api-docs/orderPrint.md` | 订单小票打印。 |
| `work_store/api-docs/dishSalesVolumeDetail.md` | 菜品销量明细。 |
| `work_store/api-docs/sopDhPay.md` | 大华闸机支付。 |
| `work_store/api-docs/dishesRecognizeImg.md` | 菜品识别图片上传和列表。 |
| `work_store/api-docs/subsidyImport.md` | 补贴批量导入。 |
| `work_store/db/dish_sales_volume_detail_tables.md` | 菜品销量明细相关表说明。 |
| `work_store/db/ydy_dishes_cate.md` | 菜品分类表说明。 |
| `work_store/doc/芯烨80系列中文编程手册.pdf` | 芯烨打印机编程手册。 |
| `work_store/doc/芯烨云开放API开发接入文档v1.9.1.pdf` | 芯烨云开放 API 文档。 |
| `work_store/qa/` | 常见问题排查笔记，例如上传 500、Docker 权限、PHP gd、SQL mode、人员导入公式错误。 |

### `work_ai_api/` AI运动营养师 API 资料

| 文件 | 作用 |
| --- | --- |
| `work_ai_api/PROJECT_NOTES.md` | ai_api 项目理解摘要，包含 ThinkPHP6 结构、入口、规范和强制改密说明。 |
| `work_ai_api/PSBC_DEBUG_NOTES.md` | 邮储支付 / 联合登录排障笔记。 |
| `work_ai_api/api-docs/README.md` | ai_api 接口文档索引。 |
| `work_ai_api/api-docs/wellandScaleSuggestion.md` | 体脂健康建议接口说明。 |

### `work_ai_store/` 和 `work_ai_app/`

| 文件 | 作用 |
| --- | --- |
| `work_ai_store/README.md` | AI运动营养师 PC 端资料区说明。 |
| `work_ai_app/README.md` | AI运动营养师 uniapp 小程序资料区说明。 |

### `work_company_knowledge/` 公司微盘知识库

| 文件或目录 | 作用 |
| --- | --- |
| `work_company_knowledge/README.md` | 企业微信微盘派生知识库入口，说明产品、交付、开发等角色如何使用索引。 |
| `work_company_knowledge/knowledge-map.md` | 两个微盘目录的文件规模、知识域、角色分类和文档类型总览。 |
| `work_company_knowledge/source-roots.md` | 姜阳本机企业微信微盘原始路径登记。 |
| `work_company_knowledge/indexes/file-inventory.tsv` | 全量文件索引，只保存元数据和源路径，不复制原始文件。 |
| `work_company_knowledge/indexes/document-index.tsv` | Word、PDF、PPT、Excel、Markdown、文本、CSV 等文档类索引。 |
| `work_company_knowledge/indexes/project-index.tsv` | 项目/主题级汇总，适合先判断某项目资料是否存在。 |
| `work_company_knowledge/indexes/category-summary.tsv` | 按来源、知识域、角色、阶段、文件类型聚合。 |
| `work_company_knowledge/indexes/role-entrypoints.tsv` | 产品、交付、开发、售前、管理等角色入口。 |
| `control/scripts/build_company_wedrive_knowledge.py` | 重新扫描企业微信微盘并生成派生索引的脚本。 |

### `work_sch1.0new/` 体育训练管理系统资料

| 文件或目录 | 作用 |
| --- | --- |
| `work_sch1.0new/README.md` | sch1.0new 控制资料入口和默认读取顺序。 |
| `work_sch1.0new/CODE_REPOSITORY.md` | Codeup 仓库地址、clone 命令和本地路径约定。 |
| `work_sch1.0new/PROJECT_MAP.md` | ThinkPHP 5、Vue 2、数据库、权限和高风险区域地图。 |
| `work_sch1.0new/OPERATION_PLAYBOOK.md` | 未来通过 `zhctprompt` 操作 sch1.0new 的流程。 |
| `work_sch1.0new/ACCEPTANCE_CHECKLIST.md` | 登录、菜单、权限、CRUD 和交付前验收清单。 |
| `work_sch1.0new/qa/` | 问答沉淀、避坑和复盘。 |
| `work_sch1.0new/db/` | 数据库口径和 SQL 文件引用，不复制完整 SQL。 |
| `work_sch1.0new/api-docs/` | 接口说明和联调记录。 |

### `work_ydysskz/` 运动员膳食 / 智慧餐厅运动员版本资料

| 文件或目录 | 作用 |
| --- | --- |
| `work_ydysskz/README.md` | ydysskz 控制资料入口和默认读取顺序。 |
| `work_ydysskz/CODE_REPOSITORY.md` | Codeup 仓库地址、clone 命令、本地路径和分支约定。 |
| `work_ydysskz/PROJECT_MAP.md` | ThinkPHP、多端前端、客户配置目录和高风险区域地图。 |
| `work_ydysskz/OPERATION_PLAYBOOK.md` | 未来通过 `zhctprompt` 操作 ydysskz 的流程。 |
| `work_ydysskz/ACCEPTANCE_CHECKLIST.md` | 分支、配置、构建、PHP 检查和部署验收清单。 |
| `work_ydysskz/deployment/` | 部署记录、版本记录、服务器路径和回滚说明。 |
| `work_ydysskz/qa/` | 问答沉淀、避坑和复盘。 |

### `work_qc/` 智慧食堂售前轻采集系统资料

| 文件或目录 | 作用 |
| --- | --- |
| `work_qc/README.md` | qc 控制资料入口和默认读取顺序。 |
| `work_qc/CODE_REPOSITORY.md` | Codeup 仓库地址、clone 命令和本地路径约定。 |
| `work_qc/PROJECT_MAP.md` | Vite、React、TypeScript、路由、导出和高风险区域地图。 |
| `work_qc/OPERATION_PLAYBOOK.md` | 未来通过 `zhctprompt` 操作 qc 的流程。 |
| `work_qc/COLLABORATION_CONTROL.md` | `qc` 接入 `zhctprompt` 两个 AI Agent 的协作和售前方案回调协议。 |
| `work_qc/ACCEPTANCE_CHECKLIST.md` | 表单、照片、录音、导入导出、构建和静态部署验收清单。 |
| `work_qc/qa/` | 问答沉淀、避坑和复盘。 |
| `work_qc/db/` | 本地存储与未来数据口径。 |
| `work_qc/api-docs/` | 接口说明和未来集成记录。 |

### `work_playwright_ui_tests/` Playwright UI 自动化测试仓库资料

| 文件或目录 | 作用 |
| --- | --- |
| `work_playwright_ui_tests/README.md` | Playwright 测试仓库控制资料入口和默认读取顺序。 |
| `work_playwright_ui_tests/CODE_REPOSITORY.md` | Codeup 仓库地址、clone 命令和本地路径约定。 |
| `work_playwright_ui_tests/PROJECT_MAP.md` | Playwright、项目配置、Page Object、flows、reporter、脚本和报告证据地图。 |
| `work_playwright_ui_tests/OPERATION_PLAYBOOK.md` | 未来通过 `zhctprompt` 操作 UI 自动化测试仓库的流程。 |
| `work_playwright_ui_tests/ACCEPTANCE_CHECKLIST.md` | 项目接入、测试框架、报告、视频和 AI 协作验收清单。 |
| `work_playwright_ui_tests/qa/` | 测试失败、选择器、环境变量、测试数据和报告归档复盘。 |
| `work_playwright_ui_tests/worklog/` | 执行日志、报告摘要和阶段性接入记录。 |

### `work_food_safety/` 食品安全智慧管理云平台资料

| 文件或目录 | 作用 |
| --- | --- |
| `work_food_safety/README.md` | food_safety 控制资料入口和默认读取顺序。 |
| `work_food_safety/CODE_REPOSITORY.md` | Codeup 仓库地址、clone 命令和本地路径约定。 |
| `work_food_safety/PROJECT_MAP.md` | Node 20、NestJS、Vue 3、pnpm monorepo、主要子系统和风险区域地图。 |
| `work_food_safety/OPERATION_PLAYBOOK.md` | 未来通过 `zhctprompt` 操作 food_safety 的流程。 |
| `work_food_safety/ACCEPTANCE_CHECKLIST.md` | 后端、前端、数据库和文档证据验收清单。 |
| `work_food_safety/qa/` | 问答沉淀、避坑和复盘。 |

### `work_win_deploy_guoxin/` 国信 Windows 部署仓库资料

| 文件或目录 | 作用 |
| --- | --- |
| `work_win_deploy_guoxin/README.md` | win_deploy_guoxin 控制资料入口和默认读取顺序。 |
| `work_win_deploy_guoxin/CODE_REPOSITORY.md` | Codeup 仓库地址、clone 命令和本地路径约定。 |
| `work_win_deploy_guoxin/PROJECT_MAP.md` | PowerShell、Windows Server、基础组件、配置模板和风险区域地图。 |
| `work_win_deploy_guoxin/OPERATION_PLAYBOOK.md` | 未来通过 `zhctprompt` 操作 win_deploy_guoxin 的流程。 |
| `work_win_deploy_guoxin/ACCEPTANCE_CHECKLIST.md` | Windows 部署环境、服务、端口、日志和安全验收清单。 |
| `work_win_deploy_guoxin/qa/` | 问答沉淀、避坑和复盘。 |

### `work_laidisen/` 莱迪森（南京建宁中学）智慧食堂部署资料

| 文件或目录 | 作用 |
| --- | --- |
| `work_laidisen/README.md` | 莱迪森项目控制资料入口和默认读取顺序。 |
| `work_laidisen/deployment-progress.md` | 有道部署记录脱敏后的当前进度、失败路径和下一步。 |
| `work_laidisen/OPERATION_PLAYBOOK.md` | 客户 VM 预检、VMware 控制台注意事项、基础环境和项目部署操作流程。 |
| `work_laidisen/ACCEPTANCE_CHECKLIST.md` | 客户本地部署验收清单。 |
| `work_laidisen/source-index.md` | 有道主笔记和参考笔记来源索引。 |
| `work_laidisen/qa/` | intake、排障和脱敏证据。 |

## 9. `docker/` 本地运行环境

| 文件或目录 | 作用 |
| --- | --- |
| `docker/安装部署.md` | 第一次部署的完整步骤：下载镜像、导入、拉代码、启动、访问、检查。 |
| `docker/docker.md` | Docker v2.0 镜像说明，包含容器路径、访问方式和验证命令。 |
| `docker/start_zhct.sh` | 推荐启动脚本，会启动 Docker Desktop、创建目录、启动容器、验证 Web 响应。 |
| `docker/Dockerfile` | 镜像构建文件，基于 openEuler 24.03 LTS，包含 Nginx、PHP 7.3、PHP 7.4。 |
| `docker/scripts/entrypoint.sh` | 容器入口脚本，创建目录、修正日志路径、启动 PHP-FPM 和 Nginx。 |
| `docker/cron/zhct` | 容器内定时任务配置。 |
| `docker/patches/php7.3-icu74.patch` | PHP 7.3 兼容 ICU 74 的构建补丁。 |
| `docker/config/` | Nginx、PHP、PHP-FPM 等配置文件。 |
| `docker/work/README.md` | Docker 调试过程和镜像工作笔记。 |
| `docker/.gitignore` | 忽略镜像包等大文件。 |
| `docker/zhctapp_v2.0_arm64.tar.gz` | Docker v2.0 arm64 镜像包。本文件较大，通常通过资源服务器分发，不应提交到 Git。 |

## 10. 常见工作流

### 想了解某个项目

1. 先看 `work/PROJECT_DIRECTOR_NOTES.md`。
2. 如果是智慧餐厅，看 `work_store/README.zhct-notes.md`。
3. 如果是 AI API，看 `work_ai_api/PROJECT_NOTES.md`。
4. 如果是 `sch1.0new`，看 `work_sch1.0new/README.md`。
5. 如果是 `ydysskz`、智慧餐厅运动员版本或山西体科所运动员版本，看 `work_ydysskz/README.md`。
6. 如果是 `qc`，看 `work_qc/README.md`。
7. 如果是 `playwright-ui-tests`、UI 自动化测试或验收视频报告，看 `work_playwright_ui_tests/README.md`。
8. 如果是 `food_safety`，看 `work_food_safety/README.md`。
9. 如果是 `win_deploy_guoxin`，看 `work_win_deploy_guoxin/README.md`。
10. 如果是莱迪森（南京建宁中学）部署，看 `work_laidisen/README.md`。
11. 再进入对应业务仓库读它自己的 `AGENTS.md`、`README.md` 和代码。

### 想改一个功能

1. 在 `tasks/QUEUE.md` 找 Ready 项；没有就先写任务契约。
2. 确认目标项目：`store` / `ai_api` / `ai_store` / `ai_app` / `qc` / `food_safety` / `win_deploy_guoxin`。
3. 读取目标项目自己的规则文件。
4. 如果需要修改目标项目代码，默认先在该子项目基于最新 `master` 新建任务分支，再开始改文件；客户稳定线修复例外，按 `control/customer-branch-governance.md` 从客户线上标签、客户稳定线或临时修复线处理。
5. 按 DEFINE -> PLAN -> BUILD -> VERIFY -> REVIEW -> SHIP 执行。
6. 把验证结果和证据路径写回控制项目。

同一个子项目存在并行任务时，不在原子项目目录里来回切分支。统一使用：

```text
一个任务 = 一个任务分支 = 一个 git worktree
```

推荐 worktree 放在整体目录下的 `worktrees/<repo>/<task-id>`，例如 `/Users/lqt/work/zhct/worktrees/store/VWCG-123`。并行前先确认 API、DB、权限、菜单、配置、公共组件和写路径没有冲突；有冲突时先串行锁定共享契约，再拆并行任务。

### 想补接口文档

1. 判断接口属于哪个项目。
2. `store` 接口放到 `work_store/api-docs/`。
3. `ai_api` 接口放到 `work_ai_api/api-docs/`。
4. 同步更新对应 `api-docs/README.md` 索引。

### 想做手册或视频

先读：

- `standards-stack/prompt/manual/USER_MANUAL_AND_VIDEO_PIPELINE.md`
- `standards-stack/prompt/recording/VIDEO_RECORDING_STANDARD.md`

手册和视频是正式交付物，必须有截图、视频、QC 或隐私检查证据，不能只写“已完成”。

### 想验证本地环境

Docker：

```bash
cd zhct/zhctprompt/docker
./start_zhct.sh
```

启动脚本会验证主项目、AI 项目首页，以及 AI 菜品分类接口：

```bash
curl -i 'http://127.0.0.1/aizhct/index.php?s=api/dishes.dishes/cate'
```

同时会验证 PC 端页面/接口路径约定：`http://127.0.0.1:8080/` 应返回 HTML，`http://127.0.0.1:8080/p/Restaurant/index` 应返回接口 JSON。

当前机器使用 80 端口：

```bash
cd /Users/lqt/work/zhct/zhctprompt/docker
HOST_PORT=80 ./start_zhct.sh
```

已有同名容器时，脚本会校验镜像、挂载目录和端口映射；如需并行启动另一个端口，同时指定新的 `CONTAINER_NAME`。

控制项目状态：

```bash
cd zhct/zhctprompt
git status --short -uno
```

010-cpt 项目状态快照：

> 不同同事的状态刷新根目录见 `control/local-paths.md`。

```bash
TIMEOUT_SECONDS=5 ./control/scripts/bounded-status.sh \
  /Users/jack/code/010-cpt \
  ./control/current-status.tsv
```

## 11. 停止规则

遇到下面情况不要硬做，先记录 blocker：

- 目标项目规则缺失，且任务涉及支付、权限、认证、数据库、设备控制等高风险内容。
- 目标文件已有非本次产生的用户改动。
- 缺少登录、数据库、密钥、设备、SDK、Docker 镜像等前置条件。
- 验证命令跑不了，且没有替代证据。
- 手册或视频采集会触发写入动作、审核动作或敏感信息泄露。

记录 blocker 时写清：

- blocked path
- blocked command
- observed output
- missing input
- next safe action

## 12. 一句话总结

`zhctprompt` 是项目控制台：它不承载业务代码，而是管理任务、规范、资料、环境和交付证据。新手先从 `README.md`、`AGENTS.md`、`HEARTBEAT.md`、`tasks/QUEUE.md` 读起，再根据目标项目进入 `work_*` 和 `zhctproject/*`。