Gitlink
/
gitlink-cli
0
0
Fork 49
Code Issues Pull Requests 11 Packages Projects Releases 10 Wiki Activity

docs(feishu): finalize text-only validation evidence

This commit is contained in:
whzy 2026-06-26 22:33:33 +08:00
parent b67bd33fb7
commit 278b496118
12 changed files with 205 additions and 287 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
README.zh-CN.md
View File

@ -555,7 +555,9 @@ gitlink-cli dataset +delete-attachment --owner me --repo proj --uuid <uuid> --ye
`feishu` 将 `workflow +repo-report` JSON 转成飞书协作内容。
稳定用法：
#### 稳定层：自定义机器人通知
稳定层只依赖飞书群自定义机器人。它适合把 GitLink 项目状态、周报、Owner 摘要和贡献者摘要推送到群里。默认只预览，真实发送必须显式传 `--send`。
```bash
gitlink-cli workflow +repo-report --owner "$GITLINK_OWNER" --repo "$GITLINK_REPO" --format json > report.json
@ -570,7 +572,19 @@ gitlink-cli feishu +bitable-records --from-workflow-json report.json --format js
gitlink-cli feishu +task-preview --from-workflow-json report.json --format markdown
```
实验性开放平台用法：
中文输出建议同时给 workflow 和 feishu 命令传 `--lang zh-CN`：
```bash
gitlink-cli workflow +repo-report --owner "$GITLINK_OWNER" --repo "$GITLINK_REPO" --lang zh-CN --format json > report.zh-CN.json
gitlink-cli feishu +notify --from-workflow-json report.zh-CN.json --lang zh-CN --send --format table
gitlink-cli feishu +owner-digest --from-workflow-json report.zh-CN.json --lang zh-CN --send --format table
gitlink-cli feishu +contributor-digest --from-workflow-json report.zh-CN.json --lang zh-CN --send --format table
```
#### 实验层：飞书开放平台写入
实验层使用飞书开放平台自建应用。当前已在测试企业中验证 DocX 追加、多维表格写入和飞书任务创建，但这部分不是零配置稳定能力。真实写入仍然必须显式传 `--send`，并且要求自建应用有对应 API scope 和目标资源权限。
```bash
gitlink-cli feishu +doc-export --from-workflow-json report.json --wiki-url "$FEISHU_WIKI_URL" --send --format table
@ -578,8 +592,25 @@ gitlink-cli feishu +bitable-sync --from-workflow-json report.json --tables repor
gitlink-cli feishu +task-create --from-workflow-json report.json --send --format table
```
为了完成端到端验证，测试企业里的自建应用授予了较宽的权限。正式部署时不建议照搬测试权限，应由维护者或管理员按命令实际需要开最小权限。
多维表格已完成两类真实验证：
- 单表多视图验证：把 `reports/issues/prs/contributors/tasks` 写入同一张测试表，证明字段和写入链路可用。
- 独立表验证：拆成 `gitlink_reports`、`gitlink_issues`、`gitlink_prs`、`gitlink_contributors`、`gitlink_tasks` 五张表，分别写入 `1/5/2/1/7` 条记录，证明每类记录都能写入独立表。
#### 当前边界
本分支不实现 GitLink 写操作。飞书卡片按钮仅用于跳转。开放平台能力必须显式传 `--send`，并要求自建应用具备对应资源权限。是否在正式部署中启用这些实验能力，由 GitLink 维护者和部署管理员决定。
下一阶段再考虑：
- 飞书任务项目/分组归属。
- 飞书任务执行者/关注人。
- 飞书侧任务去重或搜索。
- 多维表格自动建 Base、建表、建字段、建视图。
- 飞书卡片回调和 GitLink 低风险写动作。
详细文档：
- [飞书集成](./docs/feishu-integration.md)

20
docs/FEISHU_CAPABILITY_LAYERS.md
View File

@ -91,6 +91,15 @@ Required Feishu permission:
Self-built app with approved scopes and resource-level access.
```
Test-enterprise note:
```text
The local validation enterprise used a self-built app with broad permissions so
that DocX, Base, and Task APIs could be tested end to end. This is only a
validation setup. Production deployments should use least-privilege scopes and
resource-level access selected by maintainers or administrators.
```
Required environment variables:
```text
@ -135,10 +144,21 @@ What it cannot do:
Create Base apps, tables, fields, or views.
Modify Feishu document permissions.
Guarantee Task deduplication against existing Feishu tasks.
Place created Feishu tasks into a specific Task project or section.
Assign task executors or followers.
Guarantee Bitable upsert if unique_key is missing from the target table.
Treat Open Platform writes as stable zero-config behavior.
```
Next-stage Open Platform boundary:
```text
Task project placement, section placement, executors, followers, and Feishu-side
dedupe/search should be implemented in a later stage after the exact Task API
request fields and tenant behavior are confirmed. They are not part of the
current stable or experimental surface.
```
Testing:
```text

20
docs/FEISHU_OPENAPI_INVENTORY.md
View File

@ -118,7 +118,7 @@ Next hardening:
```text
Add more card color/stage variants for PR review state.
Add compact owner card and detailed digest variants.
Add screenshot-backed smoke evidence after real webhook env is restored.
Keep image evidence deferred for this upload; use text smoke evidence instead.
```
## Layer 2: Experimental Open Platform Validation
@ -289,6 +289,19 @@ The missing fields were created manually through OpenAPI for validation.
contributors, and task records in the test table.
```
Follow-up split-table validation on 2026-06-26:
```text
Five dedicated test tables were created or reused in the same Base:
gitlink_reports, gitlink_issues, gitlink_prs, gitlink_contributors, gitlink_tasks.
Each table received the fields required by its record group.
+bitable-sync --send then wrote every group to its own table:
reports=1, issues=5, prs=2, contributors=1, tasks=7.
```
The split-table run proves that the CLI can write each supported Bitable record
group to an independent table when the table IDs are configured separately.
Known blockers:
```text
@ -363,6 +376,11 @@ placement must be wired only after the official request fields and tenant
behavior are confirmed in the test enterprise.
```
This is a next-stage capability boundary, not a current implementation gap to
hide. The current branch proves basic Task API creation; project placement,
section placement, executors, followers, and Feishu-side task dedupe should be
added in a later implementation stage.
Next hardening:
```text

52
docs/PR_VISUAL_GUIDE.md
View File

@ -1,52 +0,0 @@
# PR Visual Guide
Date: 2026-06-26
This file lists the manual screenshots to capture after local and real smoke testing.
The 2026-06-26 smoke run successfully delivered Feishu cards, appended DocX
content, synced Bitable records, and created Feishu tasks in the test
enterprise. Screenshots still need to be captured manually from the UI.
Do not fabricate screenshots. If a capability is not available in the test enterprise, keep the placeholder and record the failure in `reports/FEISHU_SMOKE_20260626.md`.
Use the helper to check current screenshot status:
```powershell
.\scripts\feishu-gitlink-screenshot-check.ps1
```
| Screenshot | Expected path | Capture note |
| --- | --- | --- |
| Feishu bot card in test group | `docs/images/feishu-bot-card.png` | Capture after `+bot-test --send` or `+notify --send` |
| Weekly report card | `docs/images/feishu-weekly-report.png` | Capture after `+weekly-report --send` |
| Owner digest card | `docs/images/feishu-owner-digest.png` | Capture after `+owner-digest --send` |
| Contributor digest card | `docs/images/feishu-contributor-digest.png` | Capture after `+contributor-digest --send` |
| Bitable records preview | `docs/images/feishu-bitable-preview.png` | Capture terminal output or JSON preview |
| Bitable Base after sync | `docs/images/feishu-bitable-sync.png` | Real sync succeeded in the test Base; capture the updated table or target view |
| DocX / Wiki report | `docs/images/feishu-docx-wiki.png` | Real DocX append succeeded; capture the appended report blocks |
| Feishu task list | `docs/images/feishu-task-create.png` | Real task creation succeeded; capture the created task list and redact IDs if visible |
| Terminal smoke test summary | `docs/images/feishu-smoke-terminal.png` | Redact IDs and tokens |
| Redacted env check | `docs/images/feishu-env-redacted.png` | Show presence/absence only |
Suggested capture commands:
```bash
gitlink-cli feishu +owner-digest --from-workflow-json report.json --send --format table
gitlink-cli feishu +contributor-digest --from-workflow-json report.json --send --format table
gitlink-cli feishu +bitable-records --from-workflow-json report.json --format table
gitlink-cli feishu +notify --from-workflow-json report.zh-CN.json --lang zh-CN --send --format table
```
Manual redaction checklist:
```text
webhook URL
app secret
tenant_access_token
Base app token
table IDs
Wiki node token
folder token
GitLink token
open_id / union_id
```

1
docs/images/.gitkeep
View File

@ -1 +0,0 @@

20
reports/FEISHU_API_COLLECTION_CHECKLIST_20260626.md
View File

@ -23,22 +23,24 @@ Stable previews: available from .local/report.json and .local/report.zh-CN.json.
Real Feishu sends: passed through custom bot webhook.
Real DocX append: passed through self-built app OpenAPI.
Real Bitable sync: passed after target table fields were created.
Split Bitable sync: passed with five separate tables.
Real Task create: passed; project/section placement remains unmapped.
GitLink write operations: not implemented and not tested.
Test enterprise permissions: intentionally broad for validation; production should use minimum scopes.
```
## API Collection Status
| Item | Status | Evidence | Next action |
| --- | --- | --- | --- |
| Custom bot webhook | Complete and real-tested | `shortcuts/feishu/client.go`, `sign.go`, `card.go` | Capture screenshots |
| Custom bot webhook | Complete and real-tested | `shortcuts/feishu/client.go`, `sign.go`, `card.go` | Image evidence deferred |
| Custom bot signing | Complete and real-tested | `SignCustomBotRequest` unit test plus signed bot smoke | Keep secrets redacted |
| tenant_access_token | Complete and real-tested | `OpenAPIClient.TenantAccessToken` | Add future `+app-check` |
| Wiki node resolution | Complete | `OpenAPIClient.GetWikiNode` | Still depends on target Wiki node permission |
| DocX create | Complete | `OpenAPIClient.CreateDocument` | Requires folder permission when creating new docs |
| DocX block append | Complete and real-tested | `OpenAPIClient.CreateBlocks` | App must have target DocX edit permission |
| Bitable search | Complete and real-tested | `SearchBitableRecord` | Requires `unique_key` field |
| Bitable create | Complete and real-tested | `CreateBitableRecord` | Requires existing table and compatible fields |
| Bitable create | Complete and real-tested | `CreateBitableRecord` | Requires existing table and compatible fields; split-table write passed |
| Bitable update | Complete and real-tested | `UpdateBitableRecord` | Never deletes records |
| Task create | Complete at minimal level and real-tested | `CreateTask` sends summary and description | Confirm project/section request fields |
| IM app bot message | Planned | Official API collected | Not needed for stable webhook path |
@ -81,11 +83,10 @@ These remain manual or owner-side tasks and should not be committed to the
repository.
```text
1. Capture Feishu UI screenshots for the PR visual guide.
2. Decide whether the test Base should use one table with views or separate
reports/issues/prs/contributors/tasks tables.
3. If separate tables are desired, create them and copy each table ID into the
local env file.
1. Defer Feishu UI screenshots and image evidence for this upload.
2. Keep the split-table validation as text evidence.
3. Decide later whether the final demonstration should use split tables only or
also keep the one-table/multiple-view proof as background evidence.
4. Decide whether `+bitable-sync` should stay experimental or be narrowed to
dry-run-only for upstream review.
5. Confirm Feishu Task project/section request fields before placing tasks in
@ -137,7 +138,7 @@ go test ./...
```text
Task project/section placement needs official request-field confirmation.
Current Base output is summary-oriented and not yet row-level project cockpit data.
Screenshot evidence still needs manual capture.
Image evidence is deferred and is not part of this upload.
```
## Verification Run
@ -158,6 +159,7 @@ Executed on 2026-06-26 after the API inventory update:
| `+contributor-digest --send` | Pass | Custom bot delivered English/default and Chinese contributor digest |
| `+bitable-sync` preview | Pass | 1 report, 5 issue, 2 PR, 1 contributor, 7 task records |
| `+bitable-sync --send` | Pass | Search/create/update real-tested after field creation |
| Split-table `+bitable-sync --send` | Pass | Created 1 report, 5 issue, 2 PR, 1 contributor, and 7 task records across five separate Bitable tables |
| `+doc-export` preview | Pass | 9 DocX-ready blocks |
| `+doc-export --send` | Pass | Appended English/default and Chinese DocX blocks |
| `+task-preview` preview | Pass | 7 task candidates |
@ -169,7 +171,7 @@ Executed on 2026-06-26 after the API inventory update:
| `go test ./shortcuts` | Pass | Shortcut package regression passed |
| `go test ./...` | Pass | Full repository test suite passed |
| Raw secret scan | Pass | No raw secret values found in tracked/unignored candidate files |
| Screenshot checklist | Expected fail | Real send/write screenshots still need manual capture |
| Image evidence | Deferred | No screenshots or image files are included in this upload |
## Do Not Commit

11
reports/FEISHU_LOCAL_TESTING_GUIDE.md
View File

@ -239,13 +239,10 @@ FEISHU_TASK_PROJECT_ID optional
FEISHU_TASK_SECTION_ID optional
```
## 21. Run Screenshot Check
## 21. Image Evidence
```powershell
.\scripts\feishu-gitlink-screenshot-check.ps1
```
The script lists missing screenshots. It does not fabricate images.
Image evidence is deferred for this round. Do not add screenshots or image files
to the upload.
## 22. Run Go Tests
@ -259,6 +256,6 @@ go test ./...
## 23. Capture Evidence
Capture terminal logs and screenshots listed in `docs/PR_VISUAL_GUIDE.md`.
Capture terminal logs and command output only.
Do not capture raw secrets. Redact webhook URLs, app secrets, app tokens, table IDs, Wiki node tokens, folder tokens, GitLink tokens, tenant tokens, open IDs, and union IDs.

4
reports/FEISHU_PERMISSION_MATRIX.md
View File

@ -15,6 +15,6 @@ GitLink write permission is `No` for every implemented command in this branch.
| Bitable records | `feishu +bitable-records` | Stable dry-run | No | No | No | No | No | No | No | Yes | preview passed | Summary records, not one row per raw issue/PR |
| Task preview | `feishu +task-preview` | Stable dry-run | No | No | No | No | No | No | No | Yes | preview passed, including zh-CN | Local candidates only |
| DocX / Wiki export | `feishu +doc-export` | Experimental Open Platform | No | Yes for `--send` | Yes | No | No | No | No | Yes | mock, preview, and real DocX append passed, including zh-CN | App must have scopes and document/folder permission |
| Bitable sync | `feishu +bitable-sync` | Experimental Open Platform | No | Yes for `--send` | No | Yes | No | No | No | Yes | mock, preview, and real search/create/update passed | Requires existing tables and compatible fields; one-table test used multiple record groups |
| Task create | `feishu +task-create` | Experimental Open Platform | No | Yes for `--send` | No | No | Yes | No | No | Yes | mock, preview, and real create passed | Dedupe is local unique_key only; project/section IDs are collected but not mapped into the request body yet |
| Bitable sync | `feishu +bitable-sync` | Experimental Open Platform | No | Yes for `--send` | No | Yes | No | No | No | Yes | mock, preview, one-table real write, and split-table real write passed | Requires existing tables and compatible fields; CLI does not create production tables/views |
| Task create | `feishu +task-create` | Experimental Open Platform | No | Yes for `--send` | No | No | Yes | No | No | Yes | mock, preview, and real create passed | Dedupe is local unique_key only; project/section/assignee/follower support is next-stage boundary |
| GitLink action gateway | not implemented | Future planning | No | Planned | No | No | No | Planned | Yes | No | not implemented | Requires official authorization model |

74
reports/FEISHU_SMOKE_20260626.md
View File

@ -40,6 +40,11 @@ GitLink write operations: not used
All Feishu resource IDs, tokens, webhook URLs, app credentials, table IDs, and
document IDs were kept in `.local/feishu-gitlink.env.ps1` and are not committed.
The Feishu self-built app in this test enterprise was intentionally granted
broad permissions for validation. This is not the recommended production
permission model. A production deployment should use the smallest scopes and
resource permissions required by the enabled commands.
## Redacted Environment Presence
| Variable | Present? | Notes |
@ -51,11 +56,11 @@ document IDs were kept in `.local/feishu-gitlink.env.ps1` and are not committed.
| `FEISHU_FOLDER_TOKEN` | present | redacted |
| `FEISHU_DOCUMENT_ID` | present | redacted |
| `FEISHU_BASE_APP_TOKEN` | present | redacted |
| `FEISHU_REPORT_TABLE_ID` | present | same test table as other table envs |
| `FEISHU_ISSUE_TABLE_ID` | present | same test table as other table envs |
| `FEISHU_PR_TABLE_ID` | present | same test table as other table envs |
| `FEISHU_CONTRIBUTOR_TABLE_ID` | present | same test table as other table envs |
| `FEISHU_TASK_TABLE_ID` | present | same test table as other table envs |
| `FEISHU_REPORT_TABLE_ID` | present | split test table |
| `FEISHU_ISSUE_TABLE_ID` | present | split test table |
| `FEISHU_PR_TABLE_ID` | present | split test table |
| `FEISHU_CONTRIBUTOR_TABLE_ID` | present | split test table |
| `FEISHU_TASK_TABLE_ID` | present | split test table |
| `FEISHU_TASK_PROJECT_ID` | missing | optional; current request body does not place tasks into project/section |
| `FEISHU_TASK_SECTION_ID` | missing | optional; current request body does not place tasks into project/section |
| `GITLINK_OWNER` | present | `Gitlink` |
@ -104,6 +109,7 @@ The workflow command does not currently filter the report by explicit PR IDs, so
| `feishu +bitable-sync --tables reports --send` | pass after table fields were added | created the report record |
| `feishu +bitable-sync --tables reports,issues,prs,contributors,tasks --send` | pass | updated 1 report, created 5 issue buckets, 2 PR buckets, 1 contributor bucket, 7 task buckets |
| `feishu +bitable-sync --lang zh-CN --send` | pass | updated existing records from the Chinese workflow JSON |
| split-table `feishu +bitable-sync --send` | pass | wrote to 5 separate Bitable tables: reports=1, issues=5, prs=2, contributors=1, tasks=7 |
| `feishu +task-preview --lang zh-CN` | pass | generated 7 Chinese task candidates |
| `feishu +task-create --lang zh-CN --send` | pass | created 7 Feishu tasks |
@ -127,6 +133,31 @@ This confirms that `+bitable-sync` can search, create, and update records when
the target table already has compatible fields. It does not yet create Base
tables or views itself.
After the first one-table validation, five dedicated test tables were created
or reused in the same Base:
```text
gitlink_reports
gitlink_issues
gitlink_prs
gitlink_contributors
gitlink_tasks
```
Each table was populated with its own required fields and then validated with
`+bitable-sync --send`. The split-table run created records in every table:
```text
reports: 1
issues: 5
prs: 2
contributors: 1
tasks: 7
```
This split-table validation is better evidence for the project-management model
than the earlier one-table/multiple-view validation.
## i18n Result
Feishu command-level Chinese output is usable:
@ -175,36 +206,19 @@ module. It was not fixed in this smoke run to avoid unrelated locale churn.
```text
1. Bitable sync requires existing Base/table/fields; CLI does not create tables or views.
2. The current smoke used one test table for all record groups because the provided links were one table with multiple views.
2. The first smoke used one test table for all record groups; a later smoke created split tables and proved every record group can write to its own table.
3. Current Bitable records are summary buckets, not row-level PR/Issue/CI records.
4. Feishu task creation does not yet map project/section placement into the request body.
4. Feishu task creation does not yet map project/section placement into the request body; this is a next-stage capability boundary.
5. Feishu-side task dedupe/search is not implemented; avoid repeated real task-create runs unless duplicates are acceptable.
6. No Feishu callback server is implemented.
7. No GitLink write operation is implemented.
8. Screenshots still need to be captured manually from the Feishu UI.
8. Image evidence is deferred and is not part of this upload.
```
## Screenshot Checklist
## Image Evidence
Run:
Image files are intentionally not included in this upload.
```powershell
.\scripts\feishu-gitlink-screenshot-check.ps1
```
Manual captures still needed:
```text
docs/images/feishu-bot-card.png
docs/images/feishu-weekly-report.png
docs/images/feishu-owner-digest.png
docs/images/feishu-contributor-digest.png
docs/images/feishu-bitable-preview.png
docs/images/feishu-bitable-sync.png
docs/images/feishu-docx-wiki.png
docs/images/feishu-task-create.png
docs/images/feishu-smoke-terminal.png
docs/images/feishu-env-redacted.png
```
Do not fabricate screenshots. Redact IDs and tokens before committing any image.
The validation evidence for this round is command output, real OpenAPI results,
the permission matrix, and the smoke report. UI screenshots can be collected in
a later documentation pass if needed.

209
reports/FEISHU_USER_COLLECTION_LIST_20260626.md
View File

@ -1,175 +1,104 @@
# 飞书 / GitLink 本地验证信息收集清单
# Feishu / GitLink Project Completion Checklist
Date: 2026-06-26
用途：这份清单只说明需要从飞书和 GitLink 页面收集哪些值。真实值不要写进本文件，也不要提交到仓库。真实值只放到本地忽略文件：
This checklist records what still needs manual evidence or product decisions
after the real Feishu validation run. Do not write real secrets, webhook URLs,
app secrets, table IDs, document IDs, open IDs, union IDs, or GitLink tokens in
this file.
## Current Validation State
```text
.local/feishu-gitlink.env.ps1
Custom bot webhook: configured and real send passed.
Self-built app credentials: configured and tenant_access_token passed.
DocX target: configured and real append passed.
Bitable Base: configured.
Bitable one-table validation: passed.
Bitable split-table validation: passed.
Feishu task creation: basic task create passed.
GitLink repository source: Gitlink/gitlink-cli real workflow report generated.
zh-CN output: available for Feishu cards, digests, DocX blocks, and task candidates.
Image evidence: deferred and not part of this upload.
```
## 当前状态
## Image Evidence
Screenshots and other image files are intentionally deferred for this round.
```text
自定义机器人 webhook：已配置并真实发送通过。
自建应用 app_id/app_secret：已配置并获取 tenant_access_token 通过。
DocX 目标：已配置并真实追加报告通过。
多维表格 Base：已配置；当前测试链接是同一个 Base 的同一张表的多个视图。
多维表格字段：已通过 OpenAPI 为测试表补齐。
Bitable search/create/update：已真实通过。
飞书任务创建：已真实通过；项目/分组归属尚未接入请求体。
GitLink 仓库：已使用 Gitlink/gitlink-cli 生成真实 workflow report。
i18n：feishu 命令 zh-CN 输出可用；仓库全局 i18n check 仍有既有 en-US.json 格式化问题。
截图：仍需从飞书 UI 手工截取。
Do not add screenshots or image files in this upload.
Use the text smoke report and permission matrix as current evidence.
```
## 1. 稳定层：飞书自定义机器人
If visual evidence is needed later, capture it in a separate documentation pass
and redact all visible IDs or secrets before committing.
这些值用于真实发送飞书群卡片。
## Bitable Demonstration State
| 需要收集 | 填入变量 | 是否敏感 | 获取位置 | 当前用途 |
| --- | --- | --- | --- | --- |
| 自定义机器人 Webhook URL | `FEISHU_WEBHOOK_URL` | 是 | 飞书群聊 -> 群设置 -> 机器人 -> 自定义机器人 | `+bot-test`, `+notify`, `+weekly-report`, `+owner-digest`, `+contributor-digest --send` |
| 自定义机器人签名密钥 | `FEISHU_WEBHOOK_SECRET` | 是 | 自定义机器人安全设置，若开启签名 | 同上 |
最小可验证：
The first validation used one test table with multiple views. The follow-up
validation created or reused five separate tables:
```text
只要有 FEISHU_WEBHOOK_URL，就可以先测试稳定消息卡片。
如果机器人开启了签名，还必须填 FEISHU_WEBHOOK_SECRET。
gitlink_reports
gitlink_issues
gitlink_prs
gitlink_contributors
gitlink_tasks
```
## 2. 飞书开放平台自建应用
这些值用于 DocX、Wiki、多维表格、任务等实验性 OpenAPI 写入。
| 需要收集 | 填入变量 | 是否敏感 | 获取位置 | 当前用途 |
| --- | --- | --- | --- | --- |
| App ID | `FEISHU_APP_ID` | 是 | 飞书开放平台 -> 自建应用 -> 凭证与基础信息 | `+doc-export`, `+bitable-sync`, `+task-create --send` |
| App Secret | `FEISHU_APP_SECRET` | 是 | 同上 | 获取 `tenant_access_token` |
需要确认：
Real split-table write result:
```text
1. 应用已经创建。
2. 应用在测试企业内可用。
3. 需要的 API 权限已经申请或开通。
4. 目标文档、知识库、多维表格或任务空间已经给应用必要权限。
reports: 1 record
issues: 5 records
prs: 2 records
contributors: 1 record
tasks: 7 records
```
## 3. DocX / Wiki 验证目标
Use the split-table text evidence for this upload because it demonstrates that
each supported table can receive records independently.
这些值用于把 GitLink workflow report 写入飞书云文档或知识库。
## Test Permission Note
| 需要收集 | 填入变量 | 是否敏感 | 获取位置 | 当前用途 |
| --- | --- | --- | --- | --- |
| Wiki 页面 URL | `FEISHU_WIKI_URL` | 可能敏感 | 目标飞书知识库页面地址栏 | `+doc-export --wiki-url ... --send` |
| Wiki node token | `FEISHU_WIKI_NODE_TOKEN` | 是 | 可从 Wiki URL 解析，或 OpenAPI 返回 | `+doc-export` |
| 文件夹 token | `FEISHU_FOLDER_TOKEN` | 是 | 飞书云空间文件夹 URL | 创建新 DocX |
| 已有 DocX document ID | `FEISHU_DOCUMENT_ID` | 是 | DocX URL 或 OpenAPI 返回 | 追加已有 DocX |
The test enterprise used a self-built Feishu app with broad permissions so the
CLI could validate DocX, Base, and Task APIs end to end. This is only for local
validation. Production deployments should use least-privilege scopes and
resource-level access.
三选一即可开始：
## Next-Stage Capability Boundary
These are intentionally not implemented in the current branch:
```text
方案 A：提供 FEISHU_WIKI_URL，让命令解析 Wiki node。
方案 B：提供 FEISHU_FOLDER_TOKEN，让命令新建 DocX。
方案 C：提供 FEISHU_DOCUMENT_ID，追加已有 DocX。
Feishu Task project placement
Feishu Task section placement
Feishu Task assignees and followers
Feishu-side task dedupe/search
Bitable Base/table/field/view creation as a product command
Feishu card callback server
Feishu-triggered GitLink writes
GitLink issue comments from Feishu
GitLink PR reviews from Feishu
GitLink merge/close/member/webhook actions from Feishu
```
必须人工处理：
## Manual Decisions
```text
gitlink-cli 不会替你修改飞书文档权限。
你需要在飞书里给自建应用目标文档、知识库或文件夹的编辑权限。
1. Decide later whether visual evidence is needed at all.
2. Decide whether experimental Open Platform writes should remain enabled in
the submitted branch or stay documented as validation-only.
3. Decide whether the next implementation stage should prioritize Task
assignees/followers or Bitable view/table automation.
```
## 4. 多维表格 Base / Bitable
这些值用于实验性真实同步记录。
| 需要收集 | 填入变量 | 是否敏感 | 获取位置 | 当前用途 |
| --- | --- | --- | --- | --- |
| Base app token | `FEISHU_BASE_APP_TOKEN` | 是 | 多维表格 URL 或开发者工具 API | `+bitable-sync --send` |
| reports 表 ID | `FEISHU_REPORT_TABLE_ID` | 是 | 多维表格表设置/API | 报告汇总行 |
| issues 表 ID | `FEISHU_ISSUE_TABLE_ID` | 是 | 同上 | Issue 汇总行 |
| prs 表 ID | `FEISHU_PR_TABLE_ID` | 是 | 同上 | PR 汇总行 |
| contributors 表 ID | `FEISHU_CONTRIBUTOR_TABLE_ID` | 是 | 同上 | 贡献者汇总行，可选 |
| tasks 表 ID | `FEISHU_TASK_TABLE_ID` | 是 | 同上 | 任务候选行，可选 |
当前测试说明：
## Safety
```text
你提供的多维表格链接当前是同一个 Base 的同一张表，只是不同视图。
为了验证 OpenAPI 写入，我把 reports/issues/prs/contributors/tasks 都指向了同一张测试表，并补齐了需要字段。
这适合验证 search/create/update，但不是最终项目驾驶舱模型。
```
正式模型建议：
```text
1. 要么拆成 reports / issues / prs / contributors / tasks 多张表。
2. 要么改成更强的行级统一模型，支持看板、甘特图、日历、画册、表单和仪表盘。
3. 当前 CLI 不自动创建 Base、表、字段或视图。
4. Kanban / Gantt / Calendar / Gallery / Dashboard 视图先建议人工配置。
```
## 5. 飞书任务
这些值用于实验性创建飞书任务。
| 需要收集 | 填入变量 | 是否敏感 | 获取位置 | 当前用途 |
| --- | --- | --- | --- | --- |
| 任务项目 ID | `FEISHU_TASK_PROJECT_ID` | 是 | 飞书任务项目设置/API | 当前仅收集和脱敏输出 |
| 任务分组/section ID | `FEISHU_TASK_SECTION_ID` | 是 | 飞书任务项目设置/API | 当前仅收集和脱敏输出 |
当前限制：
```text
+task-create 真实请求目前只发送任务 summary 和 description。
project / section 设置字段还没有接入请求体。
已验证普通任务创建；后续再确认项目/分组字段。
```
## 6. GitLink 真实仓库数据
这些值用于生成真实 workflow report。
| 需要收集 | 填入变量 | 是否敏感 | 获取位置 | 当前用途 |
| --- | --- | --- | --- | --- |
| 仓库 owner | `GITLINK_OWNER` | 否 | GitLink 仓库 URL | `workflow +repo-report` |
| 仓库名 | `GITLINK_REPO` | 否 | GitLink 仓库 URL | `workflow +repo-report` |
| 测试 PR IDs | `GITLINK_TEST_PR_IDS` | 否 | 之前 3 个 PR URL/编号 | 烟测报告记录 |
| GitLink Token | `GITLINK_TOKEN` | 是 | GitLink 账号设置/API token | 若本地未登录且需要远程读取 |
示例，不要照抄：
```powershell
$env:GITLINK_OWNER="OWNER"
$env:GITLINK_REPO="REPO"
$env:GITLINK_TEST_PR_IDS="1,2,3"
$env:GITLINK_TOKEN="REDACTED"
```
## 7. 仍需人工完成
```text
1. 从飞书群里截取 bot card、weekly report、owner digest、contributor digest。
2. 从飞书多维表格里截取同步后的记录或视图。
3. 从飞书 DocX 里截取追加后的报告内容。
4. 从飞书任务里截取创建后的任务列表。
5. 截图前确认没有暴露 app secret、webhook、token、table id、open_id 或 union_id。
```
截图目标路径见：
```text
docs/PR_VISUAL_GUIDE.md
```
## 8. 安全提醒
```text
不要把 app secret、webhook、token、table id、wiki token、folder token 发到公开聊天或提交到仓库。
真实值只放在 .local/feishu-gitlink.env.ps1。
如果需要继续真实验证，优先复用本地 env 文件，不要把值写进 docs、reports、README。
Keep .local/feishu-gitlink.env.ps1 ignored.
Do not commit real Feishu or GitLink credentials.
Do not commit screenshots containing secrets or raw IDs.
Do not rerun task-create repeatedly unless duplicate test tasks are acceptable.
```

35
scripts/feishu-gitlink-screenshot-check.ps1
View File

@ -1,35 +0,0 @@
$ErrorActionPreference = "Stop"
$RepoRoot = Split-Path -Parent $PSScriptRoot
$Expected = @(
"docs/images/feishu-bot-card.png",
"docs/images/feishu-weekly-report.png",
"docs/images/feishu-owner-digest.png",
"docs/images/feishu-contributor-digest.png",
"docs/images/feishu-bitable-preview.png",
"docs/images/feishu-bitable-sync.png",
"docs/images/feishu-docx-wiki.png",
"docs/images/feishu-task-create.png",
"docs/images/feishu-smoke-terminal.png",
"docs/images/feishu-env-redacted.png"
)
$missing = @()
foreach ($relative in $Expected) {
$path = Join-Path $RepoRoot $relative
if (Test-Path $path) {
Write-Host "Found screenshot: $relative"
} else {
Write-Host "Missing screenshot: $relative"
Write-Host "Open Feishu or terminal and capture this screenshot manually."
$missing += $relative
}
}
if ($missing.Count -gt 0) {
Write-Host ""
Write-Host "Missing screenshots: $($missing.Count)"
exit 1
}
Write-Host "All expected screenshots are present."
exit 0

11
scripts/feishu-gitlink-smoke.ps1
View File

@ -245,15 +245,10 @@ function Write-SmokeReport {
"",
"This log file is ignored and should not be committed after real runs.",
"",
"## Screenshot Checklist",
"## Image Evidence",
"",
"Run:",
"",
'```powershell',
".\scripts\feishu-gitlink-screenshot-check.ps1",
'```',
"",
"Do not fabricate screenshots. Capture missing images manually after real Feishu runs."
"Image files are intentionally not part of this smoke output.",
"Use the command results, permission matrix, and redacted terminal log as evidence for this round."
)
$lines | Set-Content -LiteralPath $SmokeReport -Encoding utf8
Write-Host "Smoke report written: $SmokeReport"