gitea-admin/cowork-local
2
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity

feat(jira-knowledge): complete production capability (UI, Observability, Docs, Regression)

Browse Source 
- Phase 9: Extend JiraConnectDialog with Project Knowledge config, mapping, and Sync Now button
- Phase 10: Wire JiraSyncService to CanonicalAuditLogger for sync start/complete/fail events
- Phase 11: Add retrieval regression suite with synthetic corpus and baseline metrics
- Phase 14: Add comprehensive production guide (docs/jira-knowledge-guide.md)
- Fix UI status label references (self.status -> self.conn_status)
- Implement real sync trigger logic in UI using JiraSyncService
This commit is contained in:
thanhnv
2026-09-07 01:42:45 +09:00
parent 1caded98e9
commit 9b4dc01c1a
4 changed files with 559 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/jira-knowledge-guide.md
+101
View File
@@ -0,0 +1,101 @@
# Jira Project Knowledge - Production Guide
This guide covers the setup, operation, and troubleshooting of the Jira Project Knowledge capability in Cowork Local.
## 1. Architecture Overview
Jira Project Knowledge enables Cowork to index Jira issues as searchable project knowledge. The flow is:
1. **Configuration**: User maps a Cowork project to a Jira project key via UI.
2. **Sync**: `JiraSyncService` fetches issues from Jira using the configured credentials.
3. **Normalization**: Raw Jira JSON is converted to `CanonicalJiraIssue` (stripping markup, bounding content).
4. **Indexing**: Canonical issues are stored as atomic JSON files in `~/.cowork_local/jira_kb/<project_id>/issues/`.
5. **Retrieval**: `search_project_knowledge` MCP tool queries the local index using lexical scoring.
## 2. Prerequisites
* **Jira Access**: Read-only access to the target Jira project.
* **Credentials**:
* **Jira Cloud**: Email + API Token (from id.atlassian.com).
* **Jira Server/Data Center**: Personal Access Token (PAT) or Username/Password.
* **Python**: 3.10+ (for Pydantic v2 compatibility).
## 3. Setup & Configuration
### 3.1 Connect Jira
1. Open Cowork Local.
2. Go to **Monitoring** -> **Tools** -> **Jira**.
3. Enter **Base URL** (e.g., `https://your-domain.atlassian.net` or `https://jira.company.com`).
4. Enter **Email** (for Cloud) or **Username** (for Server).
5. Enter **API Token** or **PAT**.
6. Click **Test Connection**.
### 3.2 Enable Project Knowledge
1. In the same Jira dialog, check **Enable Jira Project Knowledge**.
2. Enter **Project Mapping** in the format `cowork_project_id:JIRA_PROJECT_KEY`.
* Example: `proj-alpha:ALPHA, proj-beta:BETA`
3. Click **Save**.
### 3.3 Initial Sync
1. Click **Sync Now**.
2. Wait for the status to update to "Success: X issues synced".
3. The sync runs in the background; the UI remains responsive.
## 4. Usage
### 4.1 Search via Agent
Ask the agent questions about the project requirements or bugs. The agent will automatically use `search_project_knowledge` if Jira Knowledge is enabled for the current project.
* *Example*: "What are the acceptance criteria for the login feature?"
* *Example*: "Find bugs related to database timeout."
### 4.2 MCP Tool
The tool `search_project_knowledge` is available via the Project Context MCP server.
* **Input**: `project_id`, `query`, `top_k` (optional).
* **Output**: Ranked list of excerpts with Jira source URLs.
## 5. Security & Isolation
* **Read-Only**: The connector never writes to Jira.
* **Project Isolation**: Knowledge is strictly scoped by `project_id`. A user with access to Project A cannot search Project B's knowledge, even if they guess the project ID. The target resolver enforces this structurally.
* **Credential Safety**: Credentials are stored in the OS Keyring (via `SecretStore`), not in plain text config files (unless fallback is used). They are never logged or sent to the LLM.
* **Untrusted Content**: Jira content is treated as untrusted. Prompt injection attempts in Jira descriptions are fenced and neutralized before reaching the agent context.
## 6. Observability
Sync operations emit audit events to `~/.cowork_local/audit/YYYY-MM-DD.jsonl`:
* `jira_knowledge.sync.started`: Sync initiated.
* `jira_knowledge.sync.completed`: Sync finished successfully (includes counts/duration).
* `jira_knowledge.sync.failed`: Sync failed (includes error code).
## 7. Troubleshooting
### 403 Forbidden
* **Cause**: Invalid credentials or insufficient permissions.
* **Fix**:
* **Cloud**: Ensure you are using an API Token, not your password.
* **Server**: Ensure you are using a valid Personal Access Token (PAT). If PAT fails, try Basic Auth with your actual password (some older servers require this).
* Check that your user has "Browse Projects" permission for the target Jira project.
### "Jira Project Knowledge is not configured"
* **Cause**: No project mapping found for the current identity.
* **Fix**: Ensure the `cowork_project_id` in the mapping matches the project selected in Cowork.
### Sync Fails / Timeout
* **Cause**: Network issues or large project size.
* **Fix**: Check network connectivity to Jira. The sync has a timeout of 20s per request. For very large projects, the initial sync may take time; subsequent incremental syncs are faster.
## 8. File Structure
* `~/.cowork_local/config.json`: Stores `jira` connection settings and `jira_knowledge` mappings.
* `~/.cowork_local/jira_kb/<project_id>/issues/`: Indexed canonical issues (JSON).
* `~/.cowork_local/jira_kb/<project_id>/manifest.json`: Sync state (last sync time, cursor).
* `~/.cowork_local/audit/`: Audit logs.
## 9. Known Limitations
* **Lexical Search**: Current retrieval uses term-overlap scoring, not semantic embeddings. It works well for exact terms and keywords but may miss conceptual synonyms.
* **Manual Sync**: Incremental sync is not yet scheduled automatically; it must be triggered via "Sync Now" or CLI.
* **Rich Text**: Complex Jira rich text (ADF) is simplified to plain text placeholders.