From cff1ef666b514cdb8f245bdc8ddab9e504d73eb4 Mon Sep 17 00:00:00 2001
From: root <root@localhost.localdomain>
Date: Sun, 31 May 2026 14:32:09 +0800
Subject: [PATCH] D118 L4-WRITE-005 write agent, intent to file output with
 truncation guard

---
 native-repo/modules/L4-WRITE-005.hdlp | 103 ++++++++++++++++++++++++++
 1 file changed, 103 insertions(+)
 create mode 100644 native-repo/modules/L4-WRITE-005.hdlp

diff --git a/native-repo/modules/L4-WRITE-005.hdlp b/native-repo/modules/L4-WRITE-005.hdlp
new file mode 100644
index 0000000..84b1c48
--- /dev/null
+++ b/native-repo/modules/L4-WRITE-005.hdlp
@@ -0,0 +1,103 @@
+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
+码字=忠诚地写下。不是创造。是记录意图在系统里的落点。