Refactor codebase
This commit is contained in:
iacore
@@ -0,0 +1,133 @@
|
||||
# Google Docs Comment Automation — Journey Log
|
||||
|
||||
2026-06-21
|
||||
|
||||
## Background
|
||||
|
||||
Task: review Chinese→English Buddhist translation manuscripts on Google Docs
|
||||
by adding editorial comments (the "Wade" style — anchored suggestions on
|
||||
specific text). The reviewer is an AI agent running on Hermes with API access.
|
||||
|
||||
## Phase 1: Google Workspace OAuth Setup
|
||||
|
||||
Set up OAuth2 for Google Workspace access:
|
||||
- Created Google Cloud project (932146571366)
|
||||
- Enabled APIs: Gmail, Calendar, Drive, Sheets, Docs, People
|
||||
- Created Desktop OAuth client, downloaded client_secret.json
|
||||
- Completed OAuth PKCE flow → token at ~/.hermes/google_token.json
|
||||
|
||||
Success: authenticated with scopes covering all needed services.
|
||||
|
||||
## Phase 2: Reading Documents and Comments (Success)
|
||||
|
||||
Used the Google Drive API v3 `comments.list` endpoint to fetch comments
|
||||
from existing review documents:
|
||||
|
||||
- Doc 1 (1DTzH7...): 61 人生佛教在当代的弘扬 — 121 comments
|
||||
- Doc 2 (13S_0u...): 附录 我的判教观 — 151 comments
|
||||
- Doc 3 (1LxCcX...): 16 觉醒的艺术 — 201 comments
|
||||
|
||||
Total: 473 editor comments by Wade, spanning 2026-04-17 to 2026-06-20.
|
||||
These comments were well-anchored (kix.XXXXXXXX format) and contained
|
||||
actionable editorial suggestions in Chinese.
|
||||
|
||||
## Phase 3: Pattern Analysis (Success)
|
||||
|
||||
Analyzed all 473 comments to extract systematic review rules. The editor's
|
||||
feedback follows clear patterns:
|
||||
|
||||
R1 — Active voice + "we" subject
|
||||
R2 — Noun → verb conversion
|
||||
R3 — Simplify vocabulary
|
||||
R4 — Break long sentences
|
||||
R5 — Remove unnecessary words
|
||||
R6 — Conversational / interview tone
|
||||
R7 — No -ly adverbs
|
||||
R8 — Concrete over abstract
|
||||
R9 — Terminology alignment
|
||||
R10 — Missing content detection
|
||||
R11 — Source faithfulness
|
||||
R12 — Sentence structure clarity
|
||||
R13 — Specific word fixes
|
||||
R14 — Positive feedback (随喜), naming the translator
|
||||
|
||||
Created skill: toolkit/skills/mpi-translation-review-comment/SKILL.md
|
||||
|
||||
## Phase 4: Attempting to Create Anchored Comments (Failure)
|
||||
|
||||
Task: apply the review rules to a new document
|
||||
(1NmJKNavB4IBg56ZRBdS5ux9ObRVlHPnSxVmjjXCyITs — 佛法与企业管理, translator: maple).
|
||||
|
||||
### Attempt 1: comments.create without anchor
|
||||
|
||||
Result: comments appear as document-level (unanchored). The translator has no
|
||||
way to know which text each comment refers to. User rejected this approach:
|
||||
"Without anchors, there is no way to know where the translator should edit."
|
||||
|
||||
### Attempt 2: kix anchors from Docs API response
|
||||
|
||||
Searched the document body via `documents.get` for kix segment IDs.
|
||||
Result: the Docs API response does NOT expose kix anchors. Only footer IDs
|
||||
(kix.hf0, kix.list) appear. Text segments have no kix identifiers.
|
||||
|
||||
### Attempt 3: kix anchors from HTML export
|
||||
|
||||
Exported the document as HTML via Drive API `files.export_media`.
|
||||
Result: HTML export contains NO kix IDs. Since 2021, Google Docs renders
|
||||
content on `<canvas>`, so there are no DOM nodes with kix attributes in
|
||||
the exported HTML.
|
||||
|
||||
### Attempt 4: Browser-based kix extraction
|
||||
|
||||
Tried navigating to the document via browser to extract kix IDs from the
|
||||
live page DOM. Result: requires Google sign-in. Agent cannot authenticate
|
||||
to Google in a browser session.
|
||||
|
||||
### Attempt 5: Line-based anchor format (official docs)
|
||||
|
||||
The Drive API docs describe an alternative anchor format using line numbers:
|
||||
```json
|
||||
{"region": {"kind": "drive#commentRegion", "line": 1, "rev": "head"}}
|
||||
```
|
||||
Created a test comment with this format. Pending user verification on whether
|
||||
it actually anchors in the Google Docs UI.
|
||||
|
||||
### Official Position
|
||||
|
||||
The Google Drive API documentation states (as of 2025):
|
||||
|
||||
> "The anchor is saved and returned when retrieving the comment, however
|
||||
> Google Workspace editor apps treat these comments as un-anchored comments."
|
||||
|
||||
The kix.* anchor format is Google's internal, undocumented format that has
|
||||
never been reverse-engineered. A 2016 thread on the Google Apps Script
|
||||
community confirms this has been a known limitation for nearly a decade
|
||||
with no resolution.
|
||||
|
||||
## Phase 5: Workaround
|
||||
|
||||
Created `translate-files/佛法与企业管理/review-comments.dj` — a structured
|
||||
file listing each comment with:
|
||||
- The specific text it should anchor to (quoted)
|
||||
- The comment content
|
||||
|
||||
The translator can manually add these comments in the Google Docs UI by
|
||||
selecting the quoted text and inserting each comment.
|
||||
|
||||
## Key Findings
|
||||
|
||||
1. **Reading comments works perfectly** via Drive API `comments.list`
|
||||
2. **Writing anchored comments does NOT work** — the anchor is silently
|
||||
ignored by Google Docs editor apps
|
||||
3. **The only reliable way** to add anchored comments to Google Docs is
|
||||
through the browser UI (select text → Insert → Comment), which requires
|
||||
human interaction or a headless browser with Google authentication
|
||||
4. **Google Apps Script** might support anchored comments from within
|
||||
the document environment (untested — requires different auth model)
|
||||
5. The `translation-review-comment` skill remains useful for `.dj` file
|
||||
review where `patch` can be used instead of comments
|
||||
|
||||
## Files Created
|
||||
|
||||
- toolkit/skills/mpi-translation-review-comment/SKILL.md — systematic review rule checklist
|
||||
- translate-files/佛法与企业管理/review-comments.dj — manual comment reference
|
||||
Binary file not shown.
@@ -0,0 +1,7 @@
|
||||
Deepseek V4 is fast and cheap
|
||||
V4 can hardly find more issues if you ask it to reread.
|
||||
|
||||
Minimax M3 holds the most effort, but is less capable than V4
|
||||
M3 generally finds more issues if you ask it to reread.
|
||||
|
||||
GLM thinks too much before acting.
|
||||
@@ -0,0 +1,106 @@
|
||||
# MPI Bilingual Typst Template — Design Decisions
|
||||
|
||||
## Location
|
||||
|
||||
- Repo / project root: `~/documents/mpi/`
|
||||
- Template directory (contains `lib/`): `~/documents/mpi/translate-files/`
|
||||
- Template: `translate-files/lib/mpi-bilingual-template.typ`
|
||||
- Example usage: `translate-files/从物品整理到心灵整理/mindful-organizing.typ`
|
||||
|
||||
## Goal
|
||||
|
||||
A single reusable Typst template for bilingual Chinese-English 静心学堂丛书
|
||||
publications. Host `.typ` files should contain almost no setup code — only an
|
||||
`#import`, a `#show: mpi-bilingual.with(...)` call, and the article content.
|
||||
|
||||
## Font choice
|
||||
|
||||
- **Chinese:** Noto Serif CJK SC (Google Fonts)
|
||||
- **English:** Noto Serif (Google Fonts), used as a freely available substitute
|
||||
for Times New Roman.
|
||||
|
||||
## Page and paragraph formatting
|
||||
|
||||
| Setting | Value | Rationale |
|
||||
|---|---|---|
|
||||
| Paper | A4 | Standard publication size |
|
||||
| Margins | 2.5 cm all around | Matches existing documents |
|
||||
| Body size | 10.5 pt | 五号 per the formatting guide |
|
||||
| Line spacing (`leading`) | 1.5 em | 1.5× line height per the guide |
|
||||
| Paragraph spacing | 1.5 em | Equivalent to one blank line between paragraphs |
|
||||
| Alignment | justified | Matches the existing `mindful-organizing.typ` look |
|
||||
| First-line indent | 2 em | Keeps bilingual paragraphs visually distinct |
|
||||
| Heading numbering | none | Headings are written verbatim in the host file |
|
||||
| Heading spacing | `above: 2em`, `below: 1.2em` | Clear section breaks without page breaks |
|
||||
| Footnotes | 8 pt, left aligned | Per the formatting guide |
|
||||
|
||||
## Title page
|
||||
|
||||
Titles and subtitles are passed as free Typst content (`title-cn`, `title-en`,
|
||||
`subtitle-cn`, `subtitle-en`).
|
||||
|
||||
The gap between title and subtitle uses `linebreak()` inside a single paragraph
|
||||
so the spacing follows the `line-height: 1.5` rhythm instead of an arbitrary
|
||||
`v()` length. A larger `v(1.5em)` separates the Chinese block from the English
|
||||
block.
|
||||
|
||||
## Table of contents
|
||||
|
||||
The TOC shows only English headings with dotted leaders and page numbers.
|
||||
Chinese headings are displayed as compact section headers above their English
|
||||
counterparts. This mirrors the behavior of the old `helpers.typ` but lives in
|
||||
the template.
|
||||
|
||||
## Host file contract
|
||||
|
||||
A host file should look like this and nothing else:
|
||||
|
||||
```typst
|
||||
#import "../lib/mpi-bilingual-template.typ": mpi-bilingual
|
||||
|
||||
#show: mpi-bilingual.with(
|
||||
title-cn: [中文标题],
|
||||
title-en: [English Title],
|
||||
subtitle-cn: [——副标题],
|
||||
subtitle-en: [—Subtitle],
|
||||
)
|
||||
|
||||
= 一、章节标题
|
||||
= I. Chapter Title
|
||||
|
||||
中文段落……
|
||||
|
||||
English paragraph …
|
||||
```
|
||||
|
||||
Compile with the helper script:
|
||||
|
||||
```bash
|
||||
~/documents/mpi/toolkit/scripts/compile-typst.fish ./从物品整理到心灵整理/mindful-organizing.typ [output.pdf]
|
||||
```
|
||||
|
||||
Or manually from the template directory (`~/documents/mpi/translate-files/`):
|
||||
|
||||
```bash
|
||||
cd ~/documents/mpi/translate-files
|
||||
typst compile --root . ./从物品整理到心灵整理/mindful-organizing.typ
|
||||
```
|
||||
|
||||
The `--root .` is required because the import `../lib/...` would otherwise
|
||||
escape Typst's sandbox.
|
||||
|
||||
## What is intentionally not in the template
|
||||
|
||||
- No inline helpers like `#speaker` or `#quote-cn` in host files. The template
|
||||
sets global formatting only. Dialogue speakers can be marked with `**Name:**`
|
||||
when truly needed.
|
||||
- No automatic blue styling for scripture quotes, because reliably detecting
|
||||
quoted classics in plain text requires explicit markup.
|
||||
- No per-chapter footnote numbering; Typst's default continuous numbering is
|
||||
used.
|
||||
|
||||
## References
|
||||
|
||||
- `references/静心学堂丛书英文统一格式-20260211.pdf` — MPI formatting guide
|
||||
- `translate-files/从物品整理到心灵整理/mindful-organizing.typ` — example host
|
||||
file and current reference implementation
|
||||
Reference in New Issue
Block a user