# Change Log — 2026-08-24

## 请求

1. 新增一个「公共模块」，模块下存放 `tools` 功能模块，`tools` 下再分各种子功能。
2. 建立项目上下文记忆体系：记录每次请求与更改，方案对比后落地；要求后续使用其他 CodeBuddy 账号也能无缝衔接。

## 变更

新增文件：

- `common/doc.go` — 公共模块说明（不依赖 internal、可独立抽取）
- `common/tools/doc.go` — tools 模块布局清单与封装规则
- `common/tools/md5/md5.go` — MD5 摘要（Md5Hex / Md5Bytes / Md5File）
- `common/tools/cryptox/cryptox.go` — AES-128-CBC / DES-ECB 加解密（base64 输出，密钥任意长度自动规范化）
- `common/tools/uuid/uuid.go` — 唯一 ID（New 32 位 / Short 短随机码）
- `common/tools/random/random.go` — 随机数/随机串（Int / String / Digits / Letters）
- `common/tools/timex/timex.go` — 时间工具（Format / Timestamp / StartOfDay / EndOfDay）
- `common/tools/convertx/convertx.go` — 类型转换带默认值（ToInt / ToInt64 / ToFloat64 / ToString / ToBool）
- `common/tools/strx/strx.go` — 字符串工具（命名转换 SnakeCase/CamelCase + 脱敏 MaskPhone/MaskIDCard/MaskName）
- `common/tools/slicex/slicex.go` — 泛型切片工具（Contains / Unique / Chunk / Map / Filter）
- `common/tools/ip/ip.go` — IP 工具（IsValid / LocalIP / IsInternal / ToLong / ToString）
- `common/tools/filex/filex.go` — 文件工具（Exists / IsDir / ReadString / WriteString）
- `AGENTS.md` — 项目智能体说明书（架构、规范、命令、记忆体系索引）
- `docs/change-log/2026-08-24.md` — 本文档

修改文件：

- `.gitignore` — 追加 `.workbuddy/`（本机记忆不入库）
- `PROJECT_STRUCTURE.md` — 目录树补充 `common/` 与 `docs/change-log/`（见后续提交）

验证：`go build ./...` 与 `go vet ./common/...` 全部通过。

## 决策与理由

- **公共模块放顶层 `common/` 而非 `internal/common/`**：Go 的 internal 包无法被外部模块引用，放顶层便于未来抽取为独立库/被同仓库其他服务复用。
- **tools 一律薄封装 GoFrame 内置组件**：v2.10.2 中 AES/DES 已拆为 `crypto/gaes`、`crypto/gdes`，UUID 为 `util/guid`，无 `gslicer`（用标准库 `slices` 替代）；避免重复造轮子，保持与框架一致。
- **记忆体系三层方案**（对比见下）：
  1. `AGENTS.md`（根目录）— 长期稳定规范，跨工具标准（Claude Code/CodeBuddy/Codex 等均识别），随 git 走；
  2. `docs/change-log/YYYY-MM-DD.md` — 每次请求变更的结构化记录，随 git 走，**这是跨账号衔接的关键**；
  3. `.workbuddy/memory/` — WorkBuddy 本机增强，不入库。
  - 对比过 `CLAUDE.md`（Claude Code 专属、已建议统一为 AGENTS.md）、`.cursor/rules`（Cursor 专属）、`.codebuddy/`（仅 CodeBuddy 读取）——它们都不是最大公约数，故不采用。

## 待办与风险

- 后续每次任务完成后：更新 `docs/change-log/`（当日文件追加）+ 提交 git，确保其他账号 clone 即恢复上下文。
- `convertx` 依赖 gconv 的"转换失败返回零值"行为（无法区分"0"与非法输入），需要严格转换的场景应在 service 层先校验。
- 本次变更尚未 git 提交，建议尽快 commit。