gpt-6-astra 使用手册（神山秘境项目）

🕐 时效标注（2026-09-13 文档治理）：近期设计件，口径以 TASKS 现行与契约 v1.3 为准。

编制：小齐　2026-09-07　基于实测（6 次真实调用）

v1.1（2026-09-08 21:0x · 小冈）：新增 §九 验收类任务工作流（背景：小齐验收单卡 workbuddy+qwen3.8 两小时未出——astra 双轨审同单 40 秒级；缺口=验收类长任务缺批处理模板与量化拆分公式）。

v1.2（2026-09-08 21:1x · 小齐）：据实测更正本手册两条自有结论 + §9.1/§9.4 两条——①§三「约 120 秒硬超时」只在 effort=high 档成立：medium 档实测 163.3 秒成功、finish_reason=stop、HTTP 200（材料 6425 字符 + 指令 1382 字符 + 4 份源码原文）；②max_tokens 不是硬截断：设定 3500、实测 completion_tokens=5344（超 53%）⇒ 控输出体积只能靠指令限定条数/字数；③§9.1「单次判据点 ≤2 个」偏保守：实测单次喂 3 大段、15+ 独立判断点成功并揪出派工岗自己 5 处错（含 2 个后端真 bug）⇒ 拆题理由改为「控输出质量与便于逐段人工核」，非避超时；④§9.4 反例时间戳「00:47 刘总报」库内零命中、须补出处（纪律 9），结论本身认可。v1.1/v1.2 原文均保留不删，更正以引用块追加。

🔴 v1.4（2026-09-23 01:1x · 小齐）· 本节为最高优先级，与正文冲突处一律以本节为准

背景：09-23 发现仓内长期存在两份 astra_call.py，团队包装脚本 scripts/gpt6.sh 实际调用的是带硬伤的旧版，导致本手册 §5.2 声称的修复对日常调用并不生效。当日已修复，并据此更正本手册。

① 唯一正确入口 = docs/tools/astra_call.py（经 scripts/gpt6.sh 调用，该包装脚本 09-23 已改指向）。scripts/astra_call.py 已标记 DEPRECATED，禁止新增调用。

② §五 的「完整源码」是早期非流式版（含 "stream": False），与本手册 §5.2 自相矛盾——勿照抄 §五 源码；直接用仓库 docs/tools/astra_call.py（默认流式、--timeout 1800、带 include_usage）。

③ §四「每次调用固定开销 ≈4,460 token」作废：2026-09-09 复测最小调用仅输入 89 / 输出 6，相差约 50 倍；当日 gpt6 自审亦判其作废。额度估算须按真实 usage 重新标定。

④ --timeout 默认 1800，勿改小：09-23 实测 medium 档耗时 195.7 秒（输入 1725 / 输出 3674、finish_reason=stop）⇒ 旧的 timeout=180 会本地掐断，且报错伪装成"通道故障"。

⑤ key 长度不作判据：各席位 key 长度不同（实测 51 / 48 / 49），归属只能由管理员指认——探活 200 只证明通道认这个 key，不证明这把该归你用。

⑥ §九 命令中的 ~/.workbuddy/bin/astra_call.py 路径已废弃，统一用 docs/tools/astra_call.py。

⑦ medium 档耗时区间更正为 60–196 秒（原记 60–130s）。

对象：小冈 / 阿仁 / 一号 —— 各用各的 API key，互不共享、不入库

一、这模型是什么

OpenAI 当前旗舰（2026 年这代），model ID = gpt-6-astra。

最大的价值：92 万 token 的输入容量 = 能把整个项目（表结构+端点+文档）一次性塞进去做通盘分析，这是普通模型做不到的。

已验证的本事（09-07 实测）：审代码能揪出真人漏掉的越权缺口和路径匹配漏洞，比人审更细。

二、快速开始（3 步）

第 1 步：拿到你自己的 API key

• 平台：https://zhi-api.com（智API，OpenAI 兼容中转）
• 在后台生成令牌（sk- 开头）
• 只给自己用，不共享、不发群里、不写进任何项目文件

第 2 步：存 key（本机，权限 600）

umask 077
printf '%s' '你的sk-xxx' > ~/.workbuddy/.zhiapi_key
chmod 600 ~/.workbuddy/.zhiapi_key

第 3 步：存脚本 + 跑第一条

把下面第五节的脚本存成 ~/.workbuddy/bin/astra_call.py，然后：

export ZHIAPI_KEY=$(cat ~/.workbuddy/.zhiapi_key)
export ZHIAPI_BASE='https://zhi-api.com/v1'
python3 docs/tools/astra_call.py \
  --prompt "用一句话说明你能做什么" --out /tmp/t.md \
  --effort low --max-tokens 300

看到 [astra] ✅ 结果已写入 就成了。

三、⚠️ 通道限制（实测，最重要，不看必踩坑）

这通道有约 120 秒的硬超时。 我实测的证据：

可用配方（照抄）

effort = medium          # 别用 high/xhigh，会超时
max_tokens ≤ 3500        # 单次输出别超
复杂任务 = 拆成多次调用    # 先问框架，再逐部分展开

大任务怎么拆：比如要审一个模块，别一次问完，拆成：

1. 第一次：只问"数据模型设计"
2. 第二次：只问"迁移路径"
3. 第三次：只问"代码影响面"

每次单独调用，材料可以重复喂（材料不贵，输出才贵）。

🔴 v1.2 更正（小齐 2026-09-08 21:1x 实测，本节原结论被推翻）：上表「约 120 秒硬超时」不是通道硬限，而是 effort=high 档的表现。实测反例（可复跑，元信息为脚本原样输出）：

- 配置 effort=medium + --max-tokens 3500 + --timeout 300，材料 6425 字符、指令 1382 字符

- 结果：耗时 163.3 秒、finish_reason=stop（正常收尾，非被切）、HTTP 200，产出 8909 字符

- ⇒ medium 档跑到 163.3s 仍成功，「120 秒硬超时」的说法只在 high 档成立（high 档两次都是 2分1秒被切且耗时一模一样，那更像 high 档自身的推理时长上限）。

- 另一处反常（重要）：设定 max_tokens=3500，实测 completion_tokens=5344，超出设定值 53% ⇒ 该通道的 max_tokens 不是硬截断，别拿它当输出体积的保证；要控体积只能靠指令里限定条数/字数。

- 配方修正：--timeout 默认 1800 别改小（我这次显式给 300 才够）；medium 档单次可以吃到 163 秒，所以「拆题」的理由从「避超时」改为「控输出质量与便于逐段人工核」。

四、计费参考（帮你估算额度）

实测规律：

一千万 token 能干多少：

结论：一千万很充裕，正常用能撑很久。但别拿它跑批量的小问题（固定开销 4460 不划算）。

五、调用脚本（完整源码，直接存）

🔴 2026-09-23 警告（小齐）：本节源码是早期非流式版（含 "stream": False、无 --stream 开关、无 include_usage），勿照抄。

团队唯一正确入口 = 仓库 docs/tools/astra_call.py（默认流式、--timeout 1800、带 include_usage），经 scripts/gpt6.sh 调用。

本节源码保留仅供理解原理；实际使用请直接 bash scripts/gpt6.sh ...。详见文首 v1.4 勘误 ②。

存为 ~/.workbuddy/bin/astra_call.py：

#!/usr/bin/env python3
"""gpt-6-astra 调用封装（智API zhi-api.com，OpenAI 兼容）

用法:
  python3 astra_call.py --material 材料包.md --prompt "指令" --out 结果.md
  python3 astra_call.py --material 材料包.md --prompt-file 指令.md --out 结果.md

凭据: 从环境变量 ZHIAPI_KEY 读取（不落盘、不入库）。
注意: gpt-6-astra 不支持 temperature/top_p/logprobs（传了会 400），本脚本不传。
"""
import argparse, json, os, sys, time
import urllib.request, urllib.error

BASE_URL = os.environ.get("ZHIAPI_BASE", "https://zhi-api.com/v1")
DEFAULT_MODEL = os.environ.get("ASTRA_MODEL", "gpt-6-astra")


def call(material: str, prompt: str, model: str, effort: str, max_tokens: int, timeout: int):
    key = os.environ.get("ZHIAPI_KEY")
    if not key:
        sys.exit("❌ 未设置环境变量 ZHIAPI_KEY（凭据不落盘，请 export ZHIAPI_KEY=你的令牌）")

    payload = {
        "model": model,
        "messages": [
            {"role": "system", "content": "你是资深系统架构师与产品战略顾问，精通复杂业务系统的架构评审、数据模型设计与商业化模型分析。回答用中文，结构化输出，结论先行，每条判断必须给出依据。禁止编造事实，材料里没有的信息明确标注『材料未涉及』。"},
            {"role": "user", "content": (prompt + "\n\n===== 项目材料 =====\n" + material) if material else prompt},
        ],
        "reasoning_effort": effort,
        "max_tokens": max_tokens,
        "stream": False,
    }

    req = urllib.request.Request(
        BASE_URL + "/chat/completions",
        data=json.dumps(payload).encode("utf-8"),
        headers={"Content-Type": "application/json", "Authorization": "Bearer " + key},
        method="POST",
    )
    t0 = time.time()
    try:
        with urllib.request.urlopen(req, timeout=timeout) as r:
            resp = json.loads(r.read().decode("utf-8"))
    except urllib.error.HTTPError as e:
        sys.exit(f"❌ HTTP {e.code}: {e.read().decode('utf-8', 'ignore')[:800]}")
    except Exception as e:
        sys.exit(f"❌ 请求失败: {e}")

    choice = resp.get("choices", [{}])[0]
    text = choice.get("message", {}).get("content", "")
    usage = resp.get("usage", {})
    meta = {
        "耗时秒": round(time.time() - t0, 1),
        "模型": resp.get("model", model),
        "输入token": usage.get("prompt_tokens"),
        "输出token": usage.get("completion_tokens"),
        "结束原因": choice.get("finish_reason"),
    }
    return text, meta


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--material", help="材料包文件路径")
    ap.add_argument("--prompt", help="分析指令（字符串）")
    ap.add_argument("--prompt-file", help="分析指令文件路径")
    ap.add_argument("--out", required=True, help="结果输出文件")
    ap.add_argument("--model", default=DEFAULT_MODEL)
    ap.add_argument("--effort", default="medium", choices=["low", "medium", "high", "xhigh"])
    ap.add_argument("--max-tokens", type=int, default=3500)
    ap.add_argument("--timeout", type=int, default=1800)
    a = ap.parse_args()

    material = ""
    if a.material:
        material = open(a.material, encoding="utf-8").read()
    prompt = a.prompt or (open(a.prompt_file, encoding="utf-8").read() if a.prompt_file else "")
    if not prompt:
        sys.exit("❌ 需要 --prompt 或 --prompt-file")

    print(f"[astra] 材料 {len(material)} 字符 | 指令 {len(prompt)} 字符 | model={a.model} effort={a.effort}")
    text, meta = call(material, prompt, a.model, a.effort, a.max_tokens, a.timeout)

    with open(a.out, "w", encoding="utf-8") as f:
        f.write(text)
    print("[astra] 调用元信息:", json.dumps(meta, ensure_ascii=False))
    print(f"[astra] ✅ 结果已写入 {a.out}（{len(text)} 字符）")


if __name__ == "__main__":
    main()

✅ 默认参数与端点已落地（2026-09-09 20:2x · 小齐）：本节源码与本机脚本 ~/.workbuddy/bin/astra_call.py 已同步改好——--effort 默认 high→medium、--max-tokens 默认 32000→3500、默认端点 https://api.zhiapi.com/v1→https://zhi-api.com/v1（实测前者 HTTP 000 连不上、后者 HTTP 200）。照抄即用，无需手敲；--timeout 保持 1800 勿改小。

5.2 脚本已入库（2026-09-09 20:3x · 小齐补写）

说明：本节由小齐补写。小冈 d955f7e 的提交信息称「手册 §5.2 补脚本入库指引」，但该提交实际只改了一行 html 页脚时间戳（20:30→20:37），md 零改动 ⇒ 指引并未落地，故由我按实测补齐。

位置：docs/tools/astra_call.py（仓库内，mode 100755 可执行）。密钥零硬编码——全部走 ZHIAPI_KEY 环境变量，自检命令输出 0 方可入库：

grep -acE "100\.64\.1\.230|sk-[A-Za-z0-9]{20,}|htpasswd|authorized_keys|password" docs/tools/astra_call.py
# 必须输出 0

照抄即用（从仓库拉下来就能跑）：

export ZHIAPI_KEY=<自己的 key>
export ZHIAPI_BASE='https://zhi-api.com/v1'   # 可选：脚本默认已是此值
python3 docs/tools/astra_call.py --material 材料.md --prompt "指令" --out 结果.md

入库版三处硬伤（小齐 2026-09-09 20:3x 实测修正）：

1. 默认端点错误：原为 api.zhiapi.com，实测 502 Tunnel connection failed ⇒ 已改 zhi-api.com（实测 HTTP 200）。
2. 流式是死代码：原 "stream": False 写死、且无 CLI 开关 ⇒ SSE 分支永远走不到，与「已升级 SSE、默认 stream:true」的自报不符。已加 --stream/--no-stream，默认开流式。
3. --timeout 被改小：原改成 180，与本手册 v1.2「默认 1800 别改小」冲突 ⇒ 已恢复 1800。

流式下的 usage 补偿：SSE 默认不回传 token 统计（实测输入/输出/结束原因全为 null）。脚本已加 stream_options.include_usage 并抓取 finish_reason ⇒ 现实测流式下 输入 86 / 输出 6 / 结束原因 stop 全部正常回传，可继续用于判断是否被截断。

六、🔴 脱敏红线（违反即事故）

喂给外部模型的材料，出网前必须裁剪。以下一律禁止外传：

• 服务器 IP（100.64.1.230）与 ssh 账号
• 任何 API key / token / htpasswd 凭据（含本项目的 AI 通道密钥）
• 数据库真实连接串、密码
• 真实商户联系人、电话、身份证
• 真实用户数据

标准动作：喂料前先跑一遍自检：

grep -acE "100\.64\.1\.230|sk-[A-Za-z0-9]{20,}|htpasswd|authorized_keys|password" 材料包.md
# 必须输出 0；非零就先删干净再喂

能喂的：表结构 DDL、路由清单、业务方案文档（D5 等）、代码逻辑（不含密钥）。

七、项目使用纪律

1. 模型输出一律要验收，不采信。它给的代码/SQL 必须自己跑一遍；它说"已修复"不算数。
2. 它说"材料未涉及"是好事——说明没编造。如果它对你没给的材料侃侃而谈，要警惕。
3. 它能帮你发现盲区，但决策权在人。09-07 实测：我审出 2 个问题，它审出 6 个，其中路径匹配漏洞是我漏的——把它当第二双眼睛，不是替代品。
4. 别用 high/xhigh 硬扛（会 502），拆题 + medium 是正解。
5. 用完记得看一眼输出 token，心里有数。

八、已验证的好用法（抄作业）

九、验收类任务工作流（v1.1 新增 · 单次调用只够审 1-2 个点，验收单必须批处理）

背景：验收审查=长工单行+多条判据+diff 逐条对照，天然是「大材料+多判断点」——一次调用只能吃 1-2 个判据，整单一次喂必超时或被轻量模型拖死（实测：workbuddy+qwen3.8 同单 2 小时未出；astra 双轨审同单 40 秒级）。

9.1 量化拆分公式（实测标定）

9.2 循环调用（三步）

# 第 1 步：总览轮——喂工单行+全部判据，让模型列「审查提纲」而不是直接下结论
python3 docs/tools/astra_call.py --material 工单与判据.md   --prompt "只输出审查提纲：将下列判据拆成 N 组，每组≤2个判据点，标注每组需要的 diff/证据文件名。不下结论。"   --out /tmp/audit_plan.md --effort low --max-tokens 800

# 第 2 步：逐组轮——按提纲每组一次调用（--prompt-file 换判据，材料复用）
for i in 1 2 3; do
  python3 docs/tools/astra_call.py --material "diff与证据_$i.md"     --prompt-file "/tmp/prompt_$i.md" --out "/tmp/audit_result_$i.md"     --effort medium --max-tokens 3500
done

# 第 3 步：合并轮——全部结果合并成一张判据×结论表（人工核对，禁直接采信）
python3 docs/tools/astra_call.py --material "/tmp/audit_result_*.md 合并"   --prompt "合并为一张表：判据|结论(pass/fail)|依据|建议。禁新增判断，只汇总前文。"   --out 验收报告.md --effort low --max-tokens 2000

9.3 铁律

1. 总览轮必须用 low（只拆提纲不下结论，省时间省 token）；逐组轮用 medium（深审）；合并轮用 low（纯汇总）。
2. 每个判据点必须附判定原文（工单行尾批注/报告原文）——模型不得凭记忆复述判据。
3. fail 项必须带证据命令（可复跑的 grep/curl），否则该轮作废。
4. 合并轮禁新增判断——astra 只做汇总，结论权在人。
5. 验收人抽查：合并表随机抽 2 条判据人工复跑证据命令（不采信全链自报）。

9.4 实证

• NOW-REVIEW R1（2026-09-07）：人工+astra medium 双轨，4566 入/1639 出，40 秒级出五项发现，小齐五处全认（commit 4dec338）。
• 反例：同验收量任务走 workbuddy+qwen3.8，2 小时未出（2026-09-08 00:47 刘总报）——轻量模型扛不住长文档逐条对照，不要用它跑验收。

🔴 v1.2 更正（小齐 2026-09-08 21:1x 实测，§9.1 两条上限被推翻 · 本节作者为小冈，原文保留不删）：

>

① 「单次判据点 ≤2 个」偏保守，实测单次 15+ 判断点成功。 反例可复跑：WIP-230 迁 COS 方案预审，单次调用喂 3 大段指令（体积口径自洽性／改造面漏项清单／匿名可达设计），内含 15 个以上独立判断点 + 6425 字符材料（含 4 份源码原文），effort=medium、--max-tokens 3500、--timeout 300 ⇒ 163.3 秒成功、finish_reason=stop、产出 8909 字符，且揪出派工岗自己 5 处错（含 2 个后端真 bug）。⇒ 建议把「≤2 个」改为「≤1 个主题域（可含多点）」：拆题的真正理由是控输出质量与便于逐段人工核，不是避超时。

② §9.4 反例的时间戳「2026-09-08 00:47 刘总报」在库内无出处。 核验命令（零命中）：在 docs/NOW.md、docs/NOW-REVIEW.md、docs/receipts/*.md 内查该时间戳与「qwen／两小时」，均 0 命中；派工岗自己的当日工作日志亦无此记录。刘总实际报「执行太慢、能不能用 gpt6 跑审核」的时间是 09-08 21:0x（在案）。⇒ 反例的现象可能为真，但归因与时间戳须补出处，否则违反纪律 9（每个数字须能被一条可复跑命令还原）。本节结论「不要用轻量模型跑长文档逐条验收」派工岗认可，仅要求把出处补实。

③ max_tokens 不是硬截断：设定 3500、实测 completion_tokens=5344（超 53%）⇒ 控输出体积只能靠指令限定条数/字数，别拿 max_tokens 当保证。

十、v1.3 更正（2026-09-09 20:2x · 小齐）

① §9.4 反例出处已补实。 正文写「2026-09-08 00:47 刘总报」，该时间戳库内零命中。可复跑出处：git -c core.quotepath=false show 2a22429（小冈 2026-09-08 21:0x 提交「手册升 v1.1」），其提交信息与本手册 v1.1 头部背景均记「小齐验收单卡 workbuddy+qwen3.8 两小时未出」⇒ 反例时间应为 09-08 21:0x 前后，正文「00:47」系笔误；结论「不要用轻量模型跑长文档逐条验收」成立。

② 端点默认值错误已修（见 §五）：api.zhiapi.com 实测连不上（HTTP 000），正确为 zhi-api.com（HTTP 200）。

③ 🔴 实测新观察：「每次固定开销 4,460 token」可能已过时。 2026-09-09 20:2x 实测一次最小调用（--prompt 9 字符、无材料、effort=medium）：输入 89 token、输出 6 token、耗时 3.8 秒、HTTP 200、finish_reason=stop，与 §四「发一个字也是 4,460」相差约 50 倍。⇒ 该数字可能是早期口径（含 reasoning／系统开销）或通道侧已调整，用它估算额度前须重新标定，勿直接引用。

④ astra 通道状态：已恢复可用。 省钱路由文档记 09-08 07:0x「zhi-api 的 astra 疑似停用、404 model_not_found、深审暂无可用」；2026-09-09 20:2x 复测 /models 与真实调用均 200 通过 ⇒ 深审／预审可恢复使用 astra。

有问题找小齐。 实测数据都在上面，别自己重新踩坑。