HLDP://zhuyuan/module/L4-WRITE-005
光湖人格体数据库 · 第4层认知层 · 模块5 · 码字Agent
铸渊产出 → 写入系统 · 意图→文件
D118 · 2026-05-31 · TCS-0002∞ · ICE-GL-ZY001

§0 为什么需要
  铸渊思考完了。需要把结果写成文件放进系统。
  不是给人类看的文本——是写入光湖世界的代码、模块、配置。
  码字Agent = 铸渊的笔。把意图翻译成文件，落进仓库。
  
  传统AI：输出到聊天窗口 → 关了就没。
  光湖：输出到代码仓库 → 永远在那里，下一个铸渊醒来读到。

  所有Layer 4的Agent模块都是码字Agent写进去的。
  码字Agent不判断内容是否正确——那是铸渊的职责。
  码字Agent只确保：格式正确、路径正确、写进去了。

§1 输入
  { intent: "写什么",
    target_path: "路径(相对于仓库根目录)",
    content: "内容",
    format: "hdlp" | "json" | "md" | "sh" | "conf" | "raw",
    commit_msg: "提交信息(可选,自动生成默认值)",
    push: true | false (是否推送到远程,默认true) }

§2 处理流程
  步骤1 · 格式校验
    format=hdlp → 校验HLDP语法:
      ⊢ 必须有 HLDP://zhuyuan/ 路径头
      ⊢ 必须有 §0-§n 分节
      ⊢ 必须有版权行(国作登字)和签名行(人格体编号+D+日期)
    format=json → 校验合法JSON
    format=md   → 无校验(自由文本)
    format=sh   → 校验shebang存在
    format=conf  → Nginx/apache语法校验(.conf文件)
    格式不符 → 拒绝写入 → 返回错误原因

  步骤2 · 路径检查
    检查 target_path 是否在仓库范围内
    检查是否覆盖已有文件 → 如果覆盖,保存旧版本到 .bak/
    创建目录(如果不存在)

  步骤3 · 写入文件
    通过工具Agent调用 file-write 工具
    或通过 gatekeeper exec 直接写文件
    写入前 base64 编码(避免字符集问题)
    写入后立即校验: wc -c 确认字节数匹配

  步骤4 · Git 提交
    git add <target_path>
    git commit -m "{commit_msg 或自动生成: D{epoch} {intent}}"
    push=true → git push origin main
    返回: { committed: true, commit_hash, bytes_written }

  步骤5 · 返回
    { ok: true|false,
      path: "实际写入路径",
      bytes: 字节数,
      commit: "commit hash",
      error: "错误原因(如果有)" }

§3 硬约束
  ⊢ HLDP格式文件必须通过语法校验 → 不通过拒绝写入
  ⊢ 覆盖已有文件必须先备份 → 不能丢历史
  ⊢ 写入后必须校验大小 → 不能出现阉割版
  ⊢ 不允许写入仓库外路径 → 安全边界
  ⊢ 大文件(>50KB)必须分块写入 → 防截断
  ⊢ 每次写入必须有commit → 追溯"谁在什么时候写了什么为什么"

§4 验证标准
  写入一个HLDP模块 → 码字Agent校验通过 → 写入 → Git提交 → 读回验证内容一致
  格式不符 → 拒绝 → 返回明确错误
  覆盖已有文件 → 旧文件出现在 .bak/ 目录下

§5 依赖
  工具Agent: L4-TOOL-003（提供 file-write 和 git-ops 工具）
  Gatekeeper: BS-SG-001:3911 /exec
  Forgejo: BS-SG-001 repo native-repo/
  HLDP语法规范: hldp/HLDP-EARTH-SPEC-v3.0.json

§6 与其他Agent关系
  铸渊主控 → 写完思考 → 码字Agent → 写成文件入仓库
  压缩Agent → 原文存档 → 码字Agent → hldpWrite写入
  提炼Agent → 产出大脑模型 → 码字Agent → 写入 brain/
  工具Agent → 执行结果 → 码字Agent(可选) → 写入日志
  检索Agent → 读文件 ← 码字Agent写入的文件
  缓存Agent → 大桌子T2索引 ← 码字Agent写入新文件后自动更新索引

§7 防截断机制
  D118教训: L4-COMPRESS-001第一次推送变成18行阉割版
  原因: gatekeeper exec的payload限制 + shell转义问题
  防截断方案:
    1. 大文件(>10KB)分块传输:
       本地 → base64 → 分块(每块≤8KB) → 逐块写入/tmp/
       → 服务器端 cat /tmp/chunk_* | base64 -d > target
    2. 写入后校验: if [ $(wc -c < target) -ne $expected_bytes ]; then ERROR; fi
    3. 小文件(<10KB)单次传输 → Python HTTP 直连 gatekeeper → 绕过shell转义
  码字Agent内置此机制——每次写入自动根据大小选择传输方式

HLDP://zhuyuan/module/L4-WRITE-005
铸渊 ICE-GL-ZY001 · D118 · 2026-05-31
冰朔 TCS-0002∞ · 国作登字-2026-A-00037559
码字=忠诚地写下。不是创造。是记录意图在系统里的落点。
