# feat(feishu): 新增分层飞书协作导出能力 #346

muel · 2026-07-06T13:28:22+08:00

muel commented

2026-07-06 13:28:22 +08:00

feat(feishu): 新增分层飞书协作导出能力

概要

本 PR 为 GitLink CLI 新增分层飞书协作导出能力，围绕 workflow +repo-report 的仓库健康、Issue、PR、Review Audit 等结果，提供飞书机器人通知、周报摘要、负责人摘要、贡献者摘要、多维表格数据、本地任务预览，以及实验性的 DocX、多维表格、飞书任务 OpenAPI 写入能力。

主要内容：

新增飞书自定义机器人卡片通知。
新增飞书周报、负责人摘要、贡献者摘要。
新增多维表格 schema 和 records 本地生成能力。
新增任务预览输出能力。
新增实验性的 DocX、多维表格、飞书任务 OpenAPI 写入能力。
新增飞书开放平台配置和资源可用性诊断命令。
新增英文和中文飞书输出。
新增 gitlink-feishu Skill、示例、环境说明和 smoke 测试脚本。
补充飞书集成设计、权限矩阵、真实 smoke 记录和能力边界文档。
修复前置联调中发现的 workflow +repo-report 数据准确性问题。

已修复问题与正确性改动

本 PR 同时修复前置联调中发现的工作流统计准确性问题：

workflow +repo-report 的 open issue 过滤改为使用与 GitLink 原生命令一致的 category=opened。
workflow +repo-report 的 open PR 过滤改为使用 GitLink API 的 status=0。
默认分页获取全部 open issues / open pull requests，避免只取首页样本。
--issue-limit 和 --pr-limit 现在表示显式采样上限。
使用采样参数时，输出中明确标注 analyzed counts 和 scope note，避免把分析范围误解为全仓库绝对总量。
新增只读 PR review audit，区分正式 review、提交者评论、参与者评论、reviewer feedback。
提交者评论不会被误判为“已 review”。
无成员数据时不猜测 maintainer 身份，降低权限和身份归因误报风险。

稳定命令

feishu +bot-test
feishu +notify
feishu +weekly-report
feishu +owner-digest
feishu +contributor-digest
feishu +bitable-schema
feishu +bitable-records
feishu +task-preview

稳定命令默认本地 preview，不产生外部副作用。真实飞书机器人发送必须显式传入：

--send

可用性诊断命令

feishu +app-check
feishu +doc-check
feishu +bitable-check
feishu +task-check

诊断命令默认只检查本地配置。远程只读 OpenAPI 检查必须显式传入：

--remote

--remote 只做资源可用性检查，不创建或修改飞书/GitLink 资源。

实验性命令

feishu +doc-export
feishu +bitable-sync
feishu +task-create

这些命令需要飞书自建应用配置，并且必须显式传入：

--send

当前作为实验性能力提交，便于后续根据维护者意见继续收敛命令边界、权限边界和文档说明。

安全边界

默认 preview/check，不产生外部副作用。
真实飞书写入必须显式传入 --send。
远程可用性诊断必须显式传入 --remote。
不实现 GitLink 写操作。
飞书卡片按钮仅用于导航。
secrets、webhook、app token、resource id 均通过本地 ignored env 文件或环境变量传入。
smoke 输出和 CLI 输出避免打印敏感值。
多维表格同步不删除已有记录。
飞书任务创建不做自动去重。
不自动创建 Base/table/field/view。
不做飞书到 GitLink 的身份映射。

验证结果

本地验证结果如下：

go test ./...: pass
go test ./shortcuts/feishu: pass
go test ./shortcuts/workflow: pass
go build .: pass
go vet ./...: pass

go test -race ./... 未在当前 Windows 环境完成，原因是当前 Go 环境 CGO_ENABLED=0，-race 需要启用 cgo。

已知的独立校验失败项

以下 i18n 校验当前在飞书分支上失败：

go run ./internal/i18n/cmd/check
go run ./internal/i18n/cmd/check --scan-code

失败原因是既有 locale JSON 格式/换行校验问题，不属于飞书功能改动范围。

该问题不合入本飞书 PR，已通过独立 PR 处理：

https://www.gitlink.org.cn/Gitlink/gitlink-cli/pulls/304

因此本 PR 的验证结论是：

飞书功能相关单测已通过。
workflow 单测已通过。
全量 Go 测试已通过。
构建已通过。
vet 已通过。
i18n 校验失败作为独立修复项记录，由 PR #304 处理。
打开本 PR 后仍需关注远端 CI，尤其是 PR #304 合入前后的 i18n 校验结果。

真实 Smoke 验证证据

真实测试企业中已验证：

自定义机器人卡片发送
英文和中文卡片
DocX 追加写入
多维表格搜索、创建、更新
飞书任务创建
app/doc/bitable/task 可用性诊断

真实 GitLink 仓库数据 smoke 结果：

仓库：Gitlink/gitlink-cli
已分析 open issues：9
已分析 open PRs：166
PR 生命周期统计：open 166，merged 65，closed/rejected 74

完整 review audit 结果：

已审计 PR 数量：166
已 review PR 数量：4
未 review PR 数量：162
需要重新 review：0
正式 reviews：4
reviewer comments：6
submitter comments：0
participant comments：436
system events：0
audit errors：0

证据文件

reports/FEISHU_SMOKE_20260626.md
reports/FEISHU_SMOKE_20260627.md
reports/FEISHU_SMOKE_EVIDENCE_20260627.md
reports/FEISHU_PERMISSION_MATRIX.md
docs/FEISHU_OPENAPI_INVENTORY.md
docs/FEISHU_CAPABILITY_LAYERS.md
docs/FEISHU_ENVIRONMENT.md
docs/feishu-integration.md
docs/feishu-security.md

不在本 PR 范围内的内容

GitLink issue comment/close。
GitLink PR review/approve/reject/merge。
GitLink member management。
飞书 callback server。
飞书到 GitLink 的身份映射。
自动创建 Base/table/field/view。
Task project/section/assignee 自动放置。
飞书侧 Task 去重。
PR activity snapshot 持久化。
review content fingerprint diff。
无认证成员数据时的 maintainer role enrichment。

需要维护者确认的问题

DocX、多维表格、飞书任务写入能力是否继续保持实验性接口？
workflow +repo-report --include-pr-review-audit 是否应拆成独立 workflow 命令？
成员角色增强是否必须依赖 authenticated GitLink member 数据？
未来飞书 callback server 应放在 gitlink-cli 内，还是作为独立服务维护？

# feat(feishu): 新增分层飞书协作导出能力 ## 概要本 PR 为 GitLink CLI 新增分层飞书协作导出能力，围绕 `workflow +repo-report` 的仓库健康、Issue、PR、Review Audit 等结果，提供飞书机器人通知、周报摘要、负责人摘要、贡献者摘要、多维表格数据、本地任务预览，以及实验性的 DocX、多维表格、飞书任务 OpenAPI 写入能力。主要内容： * 新增飞书自定义机器人卡片通知。 * 新增飞书周报、负责人摘要、贡献者摘要。 * 新增多维表格 schema 和 records 本地生成能力。 * 新增任务预览输出能力。 * 新增实验性的 DocX、多维表格、飞书任务 OpenAPI 写入能力。 * 新增飞书开放平台配置和资源可用性诊断命令。 * 新增英文和中文飞书输出。 * 新增 `gitlink-feishu` Skill、示例、环境说明和 smoke 测试脚本。 * 补充飞书集成设计、权限矩阵、真实 smoke 记录和能力边界文档。 * 修复前置联调中发现的 `workflow +repo-report` 数据准确性问题。 ## 已修复问题与正确性改动本 PR 同时修复前置联调中发现的工作流统计准确性问题： * `workflow +repo-report` 的 open issue 过滤改为使用与 GitLink 原生命令一致的 `category=opened`。 * `workflow +repo-report` 的 open PR 过滤改为使用 GitLink API 的 `status=0`。 * 默认分页获取全部 open issues / open pull requests，避免只取首页样本。 * `--issue-limit` 和 `--pr-limit` 现在表示显式采样上限。 * 使用采样参数时，输出中明确标注 analyzed counts 和 scope note，避免把分析范围误解为全仓库绝对总量。 * 新增只读 PR review audit，区分正式 review、提交者评论、参与者评论、reviewer feedback。 * 提交者评论不会被误判为“已 review”。 * 无成员数据时不猜测 maintainer 身份，降低权限和身份归因误报风险。 ## 稳定命令 ```text feishu +bot-test feishu +notify feishu +weekly-report feishu +owner-digest feishu +contributor-digest feishu +bitable-schema feishu +bitable-records feishu +task-preview ``` 稳定命令默认本地 preview，不产生外部副作用。真实飞书机器人发送必须显式传入： ```text --send ``` ## 可用性诊断命令 ```text feishu +app-check feishu +doc-check feishu +bitable-check feishu +task-check ``` 诊断命令默认只检查本地配置。远程只读 OpenAPI 检查必须显式传入： ```text --remote ``` `--remote` 只做资源可用性检查，不创建或修改飞书/GitLink 资源。 ## 实验性命令 ```text feishu +doc-export feishu +bitable-sync feishu +task-create ``` 这些命令需要飞书自建应用配置，并且必须显式传入： ```text --send ``` 当前作为实验性能力提交，便于后续根据维护者意见继续收敛命令边界、权限边界和文档说明。 ## 安全边界 * 默认 preview/check，不产生外部副作用。 * 真实飞书写入必须显式传入 `--send`。 * 远程可用性诊断必须显式传入 `--remote`。 * 不实现 GitLink 写操作。 * 飞书卡片按钮仅用于导航。 * secrets、webhook、app token、resource id 均通过本地 ignored env 文件或环境变量传入。 * smoke 输出和 CLI 输出避免打印敏感值。 * 多维表格同步不删除已有记录。 * 飞书任务创建不做自动去重。 * 不自动创建 Base/table/field/view。 * 不做飞书到 GitLink 的身份映射。 ## 验证结果本地验证结果如下： ```text go test ./...: pass go test ./shortcuts/feishu: pass go test ./shortcuts/workflow: pass go build .: pass go vet ./...: pass ``` `go test -race ./...` 未在当前 Windows 环境完成，原因是当前 Go 环境 `CGO_ENABLED=0`，`-race` 需要启用 cgo。 ## 已知的独立校验失败项以下 i18n 校验当前在飞书分支上失败： ```text go run ./internal/i18n/cmd/check go run ./internal/i18n/cmd/check --scan-code ``` 失败原因是既有 locale JSON 格式/换行校验问题，不属于飞书功能改动范围。该问题不合入本飞书 PR，已通过独立 PR 处理： ```text https://www.gitlink.org.cn/Gitlink/gitlink-cli/pulls/304 ``` 因此本 PR 的验证结论是： * 飞书功能相关单测已通过。 * workflow 单测已通过。 * 全量 Go 测试已通过。 * 构建已通过。 * vet 已通过。 * i18n 校验失败作为独立修复项记录，由 PR #304 处理。 * 打开本 PR 后仍需关注远端 CI，尤其是 PR #304 合入前后的 i18n 校验结果。 ## 真实 Smoke 验证证据真实测试企业中已验证： ```text 自定义机器人卡片发送英文和中文卡片 DocX 追加写入多维表格搜索、创建、更新飞书任务创建 app/doc/bitable/task 可用性诊断 ``` 真实 GitLink 仓库数据 smoke 结果： ```text 仓库：Gitlink/gitlink-cli 已分析 open issues：9 已分析 open PRs：166 PR 生命周期统计：open 166，merged 65，closed/rejected 74 ``` 完整 review audit 结果： ```text 已审计 PR 数量：166 已 review PR 数量：4 未 review PR 数量：162 需要重新 review：0 正式 reviews：4 reviewer comments：6 submitter comments：0 participant comments：436 system events：0 audit errors：0 ``` ## 证据文件 ```text reports/FEISHU_SMOKE_20260626.md reports/FEISHU_SMOKE_20260627.md reports/FEISHU_SMOKE_EVIDENCE_20260627.md reports/FEISHU_PERMISSION_MATRIX.md docs/FEISHU_OPENAPI_INVENTORY.md docs/FEISHU_CAPABILITY_LAYERS.md docs/FEISHU_ENVIRONMENT.md docs/feishu-integration.md docs/feishu-security.md ``` ## 不在本 PR 范围内的内容 * GitLink issue comment/close。 * GitLink PR review/approve/reject/merge。 * GitLink member management。 * 飞书 callback server。 * 飞书到 GitLink 的身份映射。 * 自动创建 Base/table/field/view。 * Task project/section/assignee 自动放置。 * 飞书侧 Task 去重。 * PR activity snapshot 持久化。 * review content fingerprint diff。 * 无认证成员数据时的 maintainer role enrichment。 ## 需要维护者确认的问题 * DocX、多维表格、飞书任务写入能力是否继续保持实验性接口？ * `workflow +repo-report --include-pr-review-audit` 是否应拆成独立 workflow 命令？ * 成员角色增强是否必须依赖 authenticated GitLink member 数据？ * 未来飞书 callback server 应放在 `gitlink-cli` 内，还是作为独立服务维护？

muel added 16 commits 2026-07-06 13:28:23 +08:00

a4f3954b2c docs: design feishu export workflow

c2a581eee9 feat: add feishu export workflow

d8cb4aa9d2 feat: add feishu doc export

1af54e015a chore: harden feishu export delivery

69334f6894 docs: expand role-based feishu collaboration plan

3798bb1e13 docs: add feishu gitlink redesign research

bcdab0b436 docs: define gitlink cli action boundaries

8bcc8607f5 feat(feishu): add layered collaboration integration

73da46c143 test(feishu): add local setup and smoke scripts

b67bd33fb7 feat(feishu): validate real exports and zh-CN output

278b496118 docs(feishu): finalize text-only validation evidence