diff --git a/README.zh-CN.md b/README.zh-CN.md index 6571f96..8f66dd5 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -555,7 +555,9 @@ gitlink-cli dataset +delete-attachment --owner me --repo proj --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) diff --git a/docs/FEISHU_CAPABILITY_LAYERS.md b/docs/FEISHU_CAPABILITY_LAYERS.md index d5a513f..a264741 100644 --- a/docs/FEISHU_CAPABILITY_LAYERS.md +++ b/docs/FEISHU_CAPABILITY_LAYERS.md @@ -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 diff --git a/docs/FEISHU_OPENAPI_INVENTORY.md b/docs/FEISHU_OPENAPI_INVENTORY.md index 14a96ab..1071a74 100644 --- a/docs/FEISHU_OPENAPI_INVENTORY.md +++ b/docs/FEISHU_OPENAPI_INVENTORY.md @@ -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 diff --git a/docs/PR_VISUAL_GUIDE.md b/docs/PR_VISUAL_GUIDE.md deleted file mode 100644 index e522602..0000000 --- a/docs/PR_VISUAL_GUIDE.md +++ /dev/null @@ -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 -``` diff --git a/docs/images/.gitkeep b/docs/images/.gitkeep deleted file mode 100644 index 8b13789..0000000 --- a/docs/images/.gitkeep +++ /dev/null @@ -1 +0,0 @@ - diff --git a/reports/FEISHU_API_COLLECTION_CHECKLIST_20260626.md b/reports/FEISHU_API_COLLECTION_CHECKLIST_20260626.md index 75ceafb..0063c3a 100644 --- a/reports/FEISHU_API_COLLECTION_CHECKLIST_20260626.md +++ b/reports/FEISHU_API_COLLECTION_CHECKLIST_20260626.md @@ -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 diff --git a/reports/FEISHU_LOCAL_TESTING_GUIDE.md b/reports/FEISHU_LOCAL_TESTING_GUIDE.md index 19b4405..f5c1240 100644 --- a/reports/FEISHU_LOCAL_TESTING_GUIDE.md +++ b/reports/FEISHU_LOCAL_TESTING_GUIDE.md @@ -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. diff --git a/reports/FEISHU_PERMISSION_MATRIX.md b/reports/FEISHU_PERMISSION_MATRIX.md index c781b18..4642ec7 100644 --- a/reports/FEISHU_PERMISSION_MATRIX.md +++ b/reports/FEISHU_PERMISSION_MATRIX.md @@ -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 | diff --git a/reports/FEISHU_SMOKE_20260626.md b/reports/FEISHU_SMOKE_20260626.md index f396e9d..6dedeea 100644 --- a/reports/FEISHU_SMOKE_20260626.md +++ b/reports/FEISHU_SMOKE_20260626.md @@ -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. diff --git a/reports/FEISHU_USER_COLLECTION_LIST_20260626.md b/reports/FEISHU_USER_COLLECTION_LIST_20260626.md index 0227b90..736d839 100644 --- a/reports/FEISHU_USER_COLLECTION_LIST_20260626.md +++ b/reports/FEISHU_USER_COLLECTION_LIST_20260626.md @@ -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. ``` diff --git a/scripts/feishu-gitlink-screenshot-check.ps1 b/scripts/feishu-gitlink-screenshot-check.ps1 deleted file mode 100644 index 957b728..0000000 --- a/scripts/feishu-gitlink-screenshot-check.ps1 +++ /dev/null @@ -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 diff --git a/scripts/feishu-gitlink-smoke.ps1 b/scripts/feishu-gitlink-smoke.ps1 index 80587a1..7604a38 100644 --- a/scripts/feishu-gitlink-smoke.ps1 +++ b/scripts/feishu-gitlink-smoke.ps1 @@ -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"