Agent 接入指南 · 服务器访问 / git / gpt6（v1）

总览：新 agent 接入三步走

步骤内容谁做
① 开通git 账号+密码 / SSH pem / gpt6 key 由管理员一人一套下发管理员
② gitclone（HTTPS 独立账号）→ 设署名 → 白名单纪律下干活推送新 agent
③ gpt6复制 key 文件 → 用 scripts/gpt6.sh 调用（配方铁律见下）新 agent

第一步 · 管理员开通清单（新 agent 上线前逐项打勾）

  1. git 账号：在中央裸仓（https://doc.kailashi.cn/git/kailash.git）为新 agent 建独立 HTTPS 账号（账号=代号），密码单独下发，一人一套禁止转借。
  2. 署名映射登记：服务端 pre-receive 强校验 author ↔ 账号 一一对应，新代号必须登记进校验映射（当前已登记：aren→阿仁 / coze1→扣子一号 / coze2→扣子二号 / xiaogang→小冈 / xiaoqi→小齐 / bobo→波波）。
  3. D7 例外名单（如需改 miniprogram-v2/）：该目录有目录属主闸门（属主 gangzi），例外名单在服务器 /srv/git/kailash.git/hooks/pre-receive 的 D7_EXC。新 agent 需改 v2 时由管理员追加代号。
  4. SSH 运维权限（按需）：仅运维用途，发放 kailash.pem 并协助配置 ~/.ssh/config（见第四节）。推送代码不走 SSH。
  5. gpt6 key：复制 key 文件到新 agent 机器的 ~/.workbuddy/.zhiapi_key（内容=API Key，权限 600）。

第二步 · git 使用（新 agent 照抄即可）

首次 clone（三行，改尖括号）

git clone https://<你的账号>:<你的密码>@doc.kailashi.cn/git/kailash.git
cd kailash
git config user.name  "<你的代号>"          # 必做：服务端强校验 author↔账号
git config user.email "<你的代号>@kailash.media"

验证连通（应输出 200）：

curl -s -o /dev/null -w '%{http_code}\n' -u '<你的账号>:<你的密码>' \
  'https://doc.kailashi.cn/git/kailash.git/info/refs?service=git-upload-pack'

日常工作流（推荐固定节奏）

git fetch origin main            # ① 先取远端
git rebase origin/main           # ② 变基到最新（保持线性历史）
# …干活，只 add 你自己的白名单文件…
git add path/to/你的文件          # ③ 禁止 git add -A / git add .
git commit -m "类型(范围): 一句话说明 -- 署名：<你的代号>"
git push origin <你的分支>:main   # ④ 用你自己的凭证推送，谁的代码谁自己推

六条铁律（违者被服务端拒绝或造成事故）

  1. 署名强校验：commit author 必须与 HTTPS 账号一致，代推必被拒。
  2. 禁止 git add -A：只 add 白名单文件。历史上曾因 add -A 夹带他人未提交文件（13MB+隐私配置）入库，教训见 AGENTS.md §9.7。
  3. 推送前先 fetch + rebase：远端多人高频提交，直接 push 极易冲突。
  4. 禁 root 推送：会污染裸仓权限（已发生过）。
  5. 推送代码只走 HTTPS：SSH（ssh kailash）仅运维用途。
  6. commit 尾缀署名：-- 署名：<代号>，与 docs/receipts/<代号>.md 回执制度配合。
完整规范（含共享树/工作树隔离、历史事故复盘）：仓库根 AGENTS.md §9.7 与 docs/git接入规范.md。

第三步 · gpt6（gpt-6-astra）使用

准备（一次性）

标准调用（一行版）

bash scripts/gpt6.sh --material /tmp/材料.md --out /tmp/输出.md \
  --effort medium --max-tokens 3500 --prompt "指令"
# 也可 --prompt-file /tmp/指令.md；其余参数透传 astra_call.py

配方铁律（团队实测沉淀，勿自作主张改）

  1. effort=medium、max_tokens≤3500：复杂任务拆多次（一次 1-2 问）。
  2. 流式为默认：脚本已内置 stream:true（SSE），长推理可跑 120s+ 不超时。（⚠️ 09-23 前该结论对 scripts/ 旧版不成立；修复后经 docs/tools/ 版才真生效。另：--timeout 默认 1800 勿改小——实测 medium 档跑到 195.7 秒）
  3. 探活免费：curl -s $ZHIAPI_BASE/models 不计费，先探活再发推理。（⚠️ 探活 200 只证明通道认这把 key，不证明这把 key 该归你用——归属由管理员指认，勿拿"能用"当"该用"）
  4. 脱敏自检：喂材料前 grep IP / 密钥 / 电话 / 真实姓名 / 用户数据，必须 0 命中。
  5. 502 重试铁律：失败也全额计费——连续 2 次 502 停手，1 字探测，退避 ≥10 分钟。
  6. 输出必验收再采信；大材料先自行压缩再喂（省输入 token）。
详细参数、usage 说明、历史通道状态：docs/tools/gpt6-astra-调用脚本详细使用文档-v2.md（简版：gpt6-astra-通道使用文档-v1.md）。

第四节 · SSH 服务器访问（仅运维，按需开通）

本机 ~/.ssh/config 配置样例

Host kailash
    HostName 100.64.1.230
    User ubuntu
    IdentityFile ~/.ssh/kailash.pem
    ServerAliveInterval 60

常用运维命令速查

ssh kailash 'docker ps --format "{{.Names}}"'                    # 容器清单
ssh kailash 'docker logs kailash-app --tail 50'                  # 后端日志
ssh kailash 'docker exec kailash-pg psql -U yos -d kailash -c "SELECT 1"'  # 数据库

附二 · 老成员换机快速迁移（已有账号，5 分钟）

适用：已在署名映射/凭证体系内的老成员（如阿仁 aren）换新电脑。无需任何服务器端改动——账号、author 映射、目录域属主（backend/** 的 D3_OWNERS）、回执文件全部已就位。
# ① clone（用本人凭证）
git clone https://aren:<密码>@doc.kailashi.cn/git/kailash.git kailash
cd kailash

# ② 设署名（必须与 AUTHOR_MAP 一致：aren→「阿仁」）
git config user.name  "阿仁"
git config user.email "aren@kailash.media"

# ③ 验证连通（输出 200 即通）
curl -s -o /dev/null -w '%{http_code}\n' -u 'aren:<密码>' \
  'https://doc.kailashi.cn/git/kailash.git/info/refs?service=git-upload-pack'

# ④ gpt6 key（按需）：旧机 ~/.workbuddy/.zhiapi_key 拷入，chmod 600
# ⑤ SSH pem（按需）：旧机 ~/.ssh/kailash.pem + ~/.ssh/config 的 kailash 段拷入，pem chmod 600

读仓库根 AGENTS.md §9.7 + 本文第二节铁律即可开工。

附 · 当前已接入 agent 一览（2026-09-22）

代号角色说明备注
gangzi冈子（v2 目录属主）D7_OWNERS
xiaogang小冈（R1 编排/验收）D7_EXC
coze1 / coze2扣子一号 / 二号D7_EXC
xiaoqi小齐（深验）D7_EXC
bobo波波（架构/契约）D7_EXC
aren阿仁（后端）共享 credential store 首位——新 agent 勿裸用 origin push，会误用 aren 身份被拒
新 agent 加入 = 本文档第一步清单走一遍；改动 git 服务器配置属生产操作，由管理员执行。